24277: Make it clearer that the new modules are not provisional.

Also make it clear on the contents page what chapters are about the
legacy API.

5 files changed, 38 insertions, 16 deletions

diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst
index c1b103e..57743d5 100644
--- a/Doc/library/email.contentmanager.rst
+++ b/Doc/library/email.contentmanager.rst
@@ -11,9 +11,7 @@
 
 ------------
 
-.. versionadded:: 3.4 as a :term:`provisional module <provisional package>`.
-
-.. versionchanged:: 3.6 provisional status removed.
+.. versionadded:: 3.6 [1]_
 
 
 .. class:: ContentManager()
@@ -201,3 +199,9 @@ Currently the email package provides only one concrete content manager,
        ``headername: headervalue`` or a list of ``header`` objects
        (distinguished from strings by having a ``name`` attribute), add the
        headers to *msg*.
+
+
+.. rubric:: Footnotes
+
+.. [1] Oringally added in 3.4 as a :term:`provisional module <provisional
+       package>`
diff --git a/Doc/library/email.headerregistry.rst b/Doc/library/email.headerregistry.rst
index feec497..2c830cf 100644
--- a/Doc/library/email.headerregistry.rst
+++ b/Doc/library/email.headerregistry.rst
@@ -11,9 +11,7 @@
 
 --------------
 
-.. versionadded:: 3.3 as a :term:`provisional module <provisional package>`.
-
-.. versionchanged:: 3.6 provisonal status removed.
+.. versionadded:: 3.6 [1]_
 
 Headers are represented by customized subclasses of :class:`str`.  The
 particular class used to represent a given header is determined by the
@@ -449,3 +447,9 @@ construct structured values to assign to specific headers.
       ``display_name`` is none and there is a single ``Address`` in the
       ``addresses`` list, the ``str`` value will be the same as the ``str`` of
       that single ``Address``.
+
+
+.. rubric:: Footnotes
+
+.. [1] Oringally added in 3.3 as a :term:`provisional module <provisional
+       package>`
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index c888673..95136d2 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -11,13 +11,7 @@
 
 --------------
 
-.. versionadded:: 3.4
-   the classes documented here were added :term:`provisionaly <provisional
-   package>`.
-
-.. versionchanged:: 3.6
-   provisional status removed, docs for legacy message class moved
-   to :ref:`compat32_message`.
+.. versionadded:: 3.6 [1]_
 
 The central class in the :mod:`email` package is the :class:`EmailMessage`
 class, imported from the :mod:`email.message` module.  It is the base class for
@@ -748,3 +742,10 @@ message objects.
     :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
     added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
     not need their own :mailheader:`MIME-Version` headers.
+
+
+.. rubric:: Footnotes
+
+.. [1] Oringally added in 3.4 as a :term:`provisional module <provisional
+       package>`.  Docs for legacy message class moved to
+       :ref:`compat32_message`.
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
index 0d6c27a..b499ed8 100644
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -371,9 +371,7 @@ added matters.  To illustrate::
    In addition to the settable attributes listed above that apply to all
    policies, this policy adds the following additional attributes:
 
-   .. versionadded:: 3.3 as a :term:`provisional feature <provisional package>`.
-
-   .. versionchanged:: 3.6 provisional status removed.
+   .. versionadded:: 3.6 [1]_
 
 
    .. attribute:: utf8
@@ -634,3 +632,9 @@ The header objects and their attributes are described in
 
    An instance of :class:`Compat32`, providing  backward compatibility with the
    behavior of the email package in Python 3.2.
+
+
+.. rubric:: Footnotes
+
+.. [1] Oringally added in 3.3 as a :term:`provisional feature <provisional
+       package>`.
diff --git a/Doc/library/email.rst b/Doc/library/email.rst
index 01bd380..c4187dd 100644
--- a/Doc/library/email.rst
+++ b/Doc/library/email.rst
@@ -97,6 +97,11 @@ can be useful tools.  This documentation is also relevant for applications that
 are still using the :mod:`~email.policy.compat32` API for backward
 compatibility reasons.
 
+.. versionchanged:: 3.6
+   Docs reorganized and rewritten to promote the new
+   :class:`~email.message.EmailMessage`/:class:`~email.policy.EmailPolicy`
+   API.
+
 Contents of the :mod:`email` package documentation:
 
 .. toctree::
@@ -112,6 +117,10 @@ Contents of the :mod:`email` package documentation:
 
    email.examples.rst
 
+Legacy API:
+
+.. toctree::
+
    email.compat32-message.rst
    email.mime.rst
    email.header.rst