doc: Add "extensions" to usage guide

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/contents.rst

@@ -13,6 +13,7 @@ Sphinx documentation contents
    usage/markdown
    usage/configuration
    usage/builders/index
+   usage/extensions/index
 
    intro
    man/index
@@ -21,7 +22,6 @@ Sphinx documentation contents
    setuptools
    templating
    latex
-   extensions
    extdev/index
    websupport
 

doc/ext/builtins.rst

@@ -1,25 +0,0 @@
-Builtin Sphinx extensions
--------------------------
-
-These extensions are built in and can be activated by respective entries in the
-:confval:`extensions` configuration value:
-
-.. toctree::
-
-   autodoc
-   autosectionlabel
-   autosummary
-   coverage
-   doctest
-   extlinks
-   githubpages
-   graphviz
-   ifconfig
-   imgconverter
-   inheritance
-   intersphinx
-   linkcode
-   math
-   napoleon
-   todo
-   viewcode

doc/extensions.rst

@@ -1,16 +0,0 @@
-.. _extensions:
-
-Sphinx Extensions
-=================
-
-Since many projects will need special features in their documentation, Sphinx
-allows adding "extensions" to the build process, each of which can modify almost
-any aspect of document processing.
-
-This chapter describes the extensions bundled with Sphinx.  For the API
-documentation on writing your own extension, see :ref:`dev-extensions`.
-
-.. toctree::
-
-   ext/builtins
-   ext/thirdparty

doc/glossary.rst

@@ -67,6 +67,12 @@ Glossary
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   extension
+     A custom :term:`role`, :term:`directive` or other aspect of Sphinx that
+     allows users to modify any aspect of the build process within Sphinx.
+
+     For more information, refer to :doc:`/usage/extensions/index`.
+
    master document
       The document that contains the root :rst:dir:`toctree` directive.
 

doc/usage/builders/index.rst

@@ -8,7 +8,7 @@ Builders
    :synopsis: Available built-in builder classes.
 
 These are the built-in Sphinx builders.  More builders can be added by
-:ref:`extensions <extensions>`.
+:doc:`extensions </usage/extensions/index>`.
 
 The builder's "name" must be given to the **-b** command-line option of
 :program:`sphinx-build` to select a builder.

doc/usage/configuration.rst

@@ -65,8 +65,9 @@ General configuration
 
 .. confval:: extensions
 
-   A list of strings that are module names of :ref:`extensions`. These can be
+   A list of strings that are module names of :doc:`extensions
-   extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones.
+   <extensions/index>`. These can be extensions coming with Sphinx (named
+   ``sphinx.ext.*``) or custom ones.
 
    Note that you can extend :data:`sys.path` within the conf file if your
    extensions live in another directory -- but make sure you use absolute paths.

doc/usage/extensions/index.rst

@@ -1,9 +1,50 @@
+==========
+Extensions
+==========
+
+Since many projects will need special features in their documentation, Sphinx
+allows adding "extensions" to the build process, each of which can modify
+almost any aspect of document processing.
+
+This chapter describes the extensions bundled with Sphinx.  For the API
+documentation on writing your own extension, refer to :ref:`dev-extensions`.
+
+
+Built-in extensions
+-------------------
+
+These extensions are built in and can be activated by respective entries in the
+:confval:`extensions` configuration value:
+
+.. toctree::
+
+   autodoc
+   autosectionlabel
+   autosummary
+   coverage
+   doctest
+   extlinks
+   githubpages
+   graphviz
+   ifconfig
+   imgconverter
+   inheritance
+   intersphinx
+   linkcode
+   math
+   napoleon
+   todo
+   viewcode
+
+
 Third-party extensions
 ----------------------
 
+.. todo:: This should reference the GitHub organization now
+
 You can find several extensions contributed by users in the `Sphinx Contrib`_
-repository.  It is open for anyone who wants to maintain an extension
+repository.  It is open for anyone who wants to maintain an extension publicly;
-publicly; just send a short message asking for write permissions.
+just send a short message asking for write permissions.
 
 There are also several extensions hosted elsewhere.  The `Sphinx extension
 survey <https://sphinxext-survey.readthedocs.io/>`__ and `awesome-sphinxdoc
@@ -16,15 +57,13 @@ list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
 
 .. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib
 
-
 Where to put your own extensions?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Extensions local to a project should be put within the project's directory
 structure.  Set Python's module search path, ``sys.path``, accordingly so that
-Sphinx can find them.
+Sphinx can find them.  For example, if your extension ``foo.py`` lies in the
-E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the
+``exts`` subdirectory of the project root, put into :file:`conf.py`::
-project root, put into :file:`conf.py`::
 
    import sys, os
 

doc/usage/quickstart.rst

@@ -318,12 +318,7 @@ features of intersphinx.
 More topics to be covered
 -------------------------
 
-- :doc:`Other extensions </extensions>`:
+- :doc:`Other extensions </usage/extensions/index>`:
-
-  * :doc:`/ext/math`,
-  * :doc:`/ext/viewcode`,
-  * :doc:`/ext/doctest`,
-  * ...
 - Static files
 - :doc:`Selecting a theme </theming>`
 - :doc:`/setuptools`

setup.cfg

@@ -32,7 +32,7 @@ directory = sphinx/locale/
 [flake8]
 max-line-length = 95
 ignore = E116,E241,E251,E741,I101
-exclude = .git,.tox,.venv,tests/*,build/*,doc/_build/*,sphinx/search/*,doc/ext/example*.py
+exclude = .git,.tox,.venv,tests/*,build/*,doc/_build/*,sphinx/search/*,doc/usage/extensions/example*.py
 application-import-names = sphinx
 import-order-style = smarkets