The documentation for email.generator.{Bytes,}Generator do not mention that Generator._handle_multipart_signed() exists and disables header folding for subparts of multipart/signed.

This may cause some frustration, since, as implemented, rendering a message part enclosed in multipart/signed causes headers to fold differently than rendering the respective message part individually:

>>> text = MIMEText('', 'plain', 'utf-8')
>>> text['X-X'] = 'a b c d e f g h i j k l m n o p q r s t u v w x y z a b c d e f g h i j k l m n o p'
>>> print(text.as_string())
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: base64
X-X: a b c d e f g h i j k l m n o p q r s t u v w x y z a b c d e f g h i j k
 l m n o p


>>> signed = MIMEMultipart('signed', filename='smime.p7s')
>>> signed.attach(text)
>>> print(signed.as_string())
Content-Type: multipart/signed; filename="smime.p7s";
 boundary="===============8046244967080646804=="
MIME-Version: 1.0

--===============8046244967080646804==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: base64
X-X: a b c d e f g h i j k l m n o p q r s t u v w x y z a b c d e f g h i j k l m n o p


--===============8046244967080646804==--

This breaks SMIME signatures when using the partial render to generate the signature. 

A possible workaround is to set maxheaderlen=0 for the partial render, which is the same as what Generator._handle_multipart_signed() does, but to do that one needs to know about the special processing.

Attached is a suggestion at a documentation fix that remedies this problem at least for the online docs.

The patch looks good to me if someone wants to make a PR out of it.  If you wouldn't mind digitally signing the CLA, Peter, that would make PSF legal happy, though I doubt a one sentence doc patch is really an issue.

New changeset 622935d9a69d12e125e470ce9a9ff3cad9e8e296 by Miss Islington (bot) (Saptak Sengupta) in branch 'master':
bpo-31887: Adds documentations for special multipart/signed handling (GH-4268)
https://github.com/python/cpython/commit/622935d9a69d12e125e470ce9a9ff3cad9e8e296