@@ -45,6 +45,7 @@ in any early abort case).
 Unless otherwise stated, buffers are not NUL-terminated.
 
 .. note::
+
    For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
    the length argument (int or :c:type:`Py_ssize_t`) is controlled by
    defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
 
@@ -525,11 +525,11 @@ Exception Objects
    reference, as accessible from Python through :attr:`__cause__`.
 
 
-.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx)
+.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
 
-   Set the cause associated with the exception to *ctx*.  Use *NULL* to clear
-   it.  There is no type check to make sure that *ctx* is either an exception
-   instance or :const:`None`.  This steals a reference to *ctx*.
+   Set the cause associated with the exception to *cause*.  Use *NULL* to clear
+   it.  There is no type check to make sure that *cause* is either an exception
+   instance or :const:`None`.  This steals a reference to *cause*.
 
    :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
 
 
@@ -582,6 +582,7 @@ code, or when embedding the Python interpreter:
    .. index:: module: _thread
 
    .. note::
+
       When only the main thread exists, no GIL operations are needed. This is a
       common situation (most Python programs do not use threads), and the lock
       operations slow the interpreter down a bit. Therefore, the lock is not
 
@@ -120,7 +120,7 @@ There are only a few functions special to module objects.
 
    Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
    created, or *NULL* if the module wasn't created with
-   :c:func:`PyModule_Create`.i
+   :c:func:`PyModule_Create`.
 
 .. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
 
 
@@ -357,9 +357,9 @@ attribute is considered sufficient for this determination.
 
 .. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
 
-   Return an estimated length for the object *o*. First trying to return its
-   actual length, then an estimate using ``__length_hint__``, and finally
-   returning the default value. On error ``-1`` is returned. This is the
+   Return an estimated length for the object *o*. First try to return its
+   actual length, then an estimate using :meth:`~object.__length_hint__`, and
+   finally return the default value. On error return ``-1``. This is the
    equivalent to the Python expression ``operator.length_hint(o, default)``.
 
    .. versionadded:: 3.4
 
@@ -129,6 +129,14 @@ type.
    Initializes a struct sequence type *type* from *desc* in place.
 
 
+.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
+
+   The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
+   failure.
+
+   .. versionadded:: 3.4
+
+
 .. c:type:: PyStructSequence_Desc
 
    Contains the meta information of a struct sequence type to create.
 
@@ -205,9 +205,8 @@ type objects) *must* have the :attr:`ob_size` field.
    bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
    flag bit is set, the instance should be printed the same way as :c:member:`~PyTypeObject.tp_str`
    would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
-   should be printed the same was as :c:member:`~PyTypeObject.tp_repr` would format it. It should
-   return ``-1`` and set an exception condition when an error occurred during the
-   comparison.
+   should be printed the same way as :c:member:`~PyTypeObject.tp_repr` would format it. It should
+   return ``-1`` and set an exception condition when an error occurs.
 
    It is possible that the :c:member:`~PyTypeObject.tp_print` field will be deprecated. In any case,
    it is recommended not to define :c:member:`~PyTypeObject.tp_print`, but instead to rely on
 
@@ -61,6 +61,8 @@
 # By default, highlight as Python 3.
 highlight_language = 'python3'
 
+needs_sphinx = '1.1'
+
 
 # Options for HTML output
 # -----------------------
@@ -118,11 +120,11 @@
 latex_documents = [
     ('c-api/index', 'c-api.tex',
      'The Python/C API', _stdauthor, 'manual'),
-    ('distutils/index', 'distutils.tex',
+    ('distributing/index', 'distributing.tex',
      'Distributing Python Modules', _stdauthor, 'manual'),
     ('extending/index', 'extending.tex',
      'Extending and Embedding Python', _stdauthor, 'manual'),
-    ('install/index', 'install.tex',
+    ('installing/index', 'installing.tex',
      'Installing Python Modules', _stdauthor, 'manual'),
     ('library/index', 'library.tex',
      'The Python Library Reference', _stdauthor, 'manual'),
 
@@ -11,8 +11,8 @@
    library/index.rst
    extending/index.rst
    c-api/index.rst
-   distutils/index.rst
-   install/index.rst
+   distributing/index.rst
+   installing/index.rst
    howto/index.rst
    faq/index.rst
    glossary.rst
@@ -21,3 +21,11 @@
    bugs.rst
    copyright.rst
    license.rst
+
+.. include legacy packaging docs in build
+
+.. toctree::
+   :hidden:
+
+   distutils/index.rst
+   install/index.rst
@@ -0,0 +1,143 @@
+.. _distributing-index:
+
+###############################
+  Distributing Python Modules
+###############################
+
+:Email: distutils-sig@python.org
+
+
+As a popular open source development project, Python has an active
+supporting community of contributors and users that also make their software
+available for other Python developers to use under open source license terms.
+
+This allows Python users to share and collaborate effectively, benefiting
+from the solutions others have already created to common (and sometimes
+even rare!) problems, as well as potentially contributing their own
+solutions to the common pool.
+
+This guide covers the distribution part of the process. For a guide to
+installing other Python projects, refer to the
+:ref:`installation guide <installing-index>`.
+
+.. note::
+
+   For corporate and other institutional users, be aware that many
+   organisations have their own policies around using and contributing to
+   open source software. Please take such policies into account when making
+   use of the distribution and installation tools provided with Python.
+
+
+Key terms
+=========
+
+* the `Python Package Index <https://pypi.python.org/pypi>`__ is a public
+  repository of open source licensed packages made available for use by
+  other Python users
+* the `Python Packaging Authority
+  <http://packaging.python.org/en/latest/future.html>`__ are the group of
+  developers and documentation authors responsible for the maintenance and
+  evolution of the standard packaging tools and the associated metadata and
+  file format standards. They maintain a variety of tools, documentation
+  and issue trackers on both `GitHub <https://github.com/pypa>`__ and
+  `BitBucket <https://bitbucket.org/pypa/>`__.
+* ``distutils`` is the original build and distribution system first added to
+  the Python standard library in 1998. While direct use of ``distutils`` is
+  being phased out, it still laid the foundation for the current packaging
+  and distribution infrastructure, and it not only remains part of the
+  standard library, but its name lives on in other ways (such as the name
+  of the mailing list used to coordinate Python packaging standards
+  development).
+
+
+Open source licensing and collaboration
+=======================================
+
+In most parts of the world, software is automatically covered by copyright.
+This means that other developers require explicit permission to copy, use,
+modify and redistribute the software.
+
+Open source licensing is a way of explicitly granting such permission in a
+relatively consistent way, allowing developers to share and collaborate
+efficiently by making common solutions to various problems freely available.
+This leaves many developers free to spend more time focusing on the problems
+that are relatively unique to their specific situation.
+
+The distribution tools provided with Python are designed to make it
+reasonably straightforward for developers to make their own contributions
+back to that common pool of software if they choose to do so.
+
+The same distribution tools can also be used to distribute software within
+an organisation, regardless of whether that software is published as open
+source software or not.
+
+
+Installing the tools
+====================
+
+The standard library does not include build tools that support modern
+Python packaging standards, as the core development team has found that it
+is important to have standard tools that work consistently, even on older
+versions of Python.
+
+The currently recommended build and distribution tools can be installed
+using ``pip``::
+
+    pip install setuptools wheel twine
+
+
+Reading the guide
+=================
+
+The Python Packaging User Guide covers the various key steps and elements
+involved in creating a project
+
+* `Project structure`_
+* `Building and packaging the project`_
+* `Uploading the project to the Python Package Index`_
+
+.. _Project structure: \
+   http://packaging.python.org/en/latest/tutorial.html#creating-your-own-project
+.. _Building and packaging the project: \
+   http://packaging.python.org/en/latest/tutorial.html#building-packaging-your-project
+.. _Uploading the project to the Python Package Index: \
+   http://packaging.python.org/en/latest/tutorial.html#uploading-your-project-to-pypi
+
+
+How do I...?
+============
+
+These are quick answers or links for some common tasks.
+
+... choose a name for my project?
+---------------------------------
+
+This isn't an easy topic, but here are a few tips:
+
+* check the Python Package Index to see if the name is already in use
+* check popular hosting sites like GitHub, BitBucket, etc to see if there
+  is already a project with that name
+* check what comes up in a web search for the name you're considering
+* avoid particularly common words, especially ones with multiple meanings,
+  as they can make it difficult for users to find your software when
+  searching for it
+
+
+... create and distribute binary extensions?
+--------------------------------------------
+
+This is actually quite a complex topic, with a variety of alternatives
+available depending on exactly what you're aiming to achieve. See the
+Python Packaging User Guide for more information and recommendations.
+
+.. seealso::
+
+   `Python Packaging User Guide: Binary Extensions
+   <http://packaging.python.org/en/latest/extensions.html>`__
+
+.. other topics:
+
+   Once the Development & Deployment part of PPUG is fleshed out, some of
+   those sections should be linked from new questions here (most notably,
+   we should have a question about avoiding depending on PyPI that links to
+   http://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches)