From d9ccc957173da20174271e6950988cff9e091a42 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 20:58:21 +0000 Subject: [PATCH] doc: Add "extensions" to usage guide Signed-off-by: Stephen Finucane --- doc/contents.rst | 2 +- doc/ext/builtins.rst | 25 --------- doc/extensions.rst | 16 ------ doc/glossary.rst | 6 +++ doc/usage/builders/index.rst | 2 +- doc/usage/configuration.rst | 5 +- doc/{ext => usage/extensions}/autodoc.rst | 0 .../extensions}/autosectionlabel.rst | 0 doc/{ext => usage/extensions}/autosummary.rst | 0 doc/{ext => usage/extensions}/coverage.rst | 0 doc/{ext => usage/extensions}/doctest.rst | 0 .../extensions}/example_google.py | 0 .../extensions}/example_google.rst | 0 .../extensions}/example_numpy.py | 0 .../extensions}/example_numpy.rst | 0 doc/{ext => usage/extensions}/extlinks.rst | 0 doc/{ext => usage/extensions}/githubpages.rst | 0 doc/{ext => usage/extensions}/graphviz.rst | 0 doc/{ext => usage/extensions}/ifconfig.rst | 0 .../extensions}/imgconverter.rst | 0 .../extensions/index.rst} | 51 ++++++++++++++++--- doc/{ext => usage/extensions}/inheritance.rst | 0 doc/{ext => usage/extensions}/intersphinx.rst | 0 doc/{ext => usage/extensions}/linkcode.rst | 0 doc/{ext => usage/extensions}/math.rst | 0 doc/{ext => usage/extensions}/napoleon.rst | 0 doc/{ext => usage/extensions}/todo.rst | 0 doc/{ext => usage/extensions}/viewcode.rst | 0 doc/usage/quickstart.rst | 7 +-- setup.cfg | 2 +- 30 files changed, 58 insertions(+), 58 deletions(-) delete mode 100644 doc/ext/builtins.rst delete mode 100644 doc/extensions.rst rename doc/{ext => usage/extensions}/autodoc.rst (100%) rename doc/{ext => usage/extensions}/autosectionlabel.rst (100%) rename doc/{ext => usage/extensions}/autosummary.rst (100%) rename doc/{ext => usage/extensions}/coverage.rst (100%) rename doc/{ext => usage/extensions}/doctest.rst (100%) rename doc/{ext => usage/extensions}/example_google.py (100%) rename doc/{ext => usage/extensions}/example_google.rst (100%) rename doc/{ext => usage/extensions}/example_numpy.py (100%) rename doc/{ext => usage/extensions}/example_numpy.rst (100%) rename doc/{ext => usage/extensions}/extlinks.rst (100%) rename doc/{ext => usage/extensions}/githubpages.rst (100%) rename doc/{ext => usage/extensions}/graphviz.rst (100%) rename doc/{ext => usage/extensions}/ifconfig.rst (100%) rename doc/{ext => usage/extensions}/imgconverter.rst (100%) rename doc/{ext/thirdparty.rst => usage/extensions/index.rst} (51%) rename doc/{ext => usage/extensions}/inheritance.rst (100%) rename doc/{ext => usage/extensions}/intersphinx.rst (100%) rename doc/{ext => usage/extensions}/linkcode.rst (100%) rename doc/{ext => usage/extensions}/math.rst (100%) rename doc/{ext => usage/extensions}/napoleon.rst (100%) rename doc/{ext => usage/extensions}/todo.rst (100%) rename doc/{ext => usage/extensions}/viewcode.rst (100%) diff --git a/doc/contents.rst b/doc/contents.rst index 2da3cb979..93f89f388 100644 --- a/doc/contents.rst +++ b/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 diff --git a/doc/ext/builtins.rst b/doc/ext/builtins.rst deleted file mode 100644 index 6972a5957..000000000 --- a/doc/ext/builtins.rst +++ /dev/null @@ -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 diff --git a/doc/extensions.rst b/doc/extensions.rst deleted file mode 100644 index c005218e8..000000000 --- a/doc/extensions.rst +++ /dev/null @@ -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 diff --git a/doc/glossary.rst b/doc/glossary.rst index c74409453..d3367e5df 100644 --- a/doc/glossary.rst +++ b/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. diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index ee0aa0a33..bb107162c 100644 --- a/doc/usage/builders/index.rst +++ b/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 `. +:doc:`extensions `. The builder's "name" must be given to the **-b** command-line option of :program:`sphinx-build` to select a builder. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 83700e65e..225b7fa01 100644 --- a/doc/usage/configuration.rst +++ b/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 - extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones. + A list of strings that are module names of :doc:`extensions + `. 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. diff --git a/doc/ext/autodoc.rst b/doc/usage/extensions/autodoc.rst similarity index 100% rename from doc/ext/autodoc.rst rename to doc/usage/extensions/autodoc.rst diff --git a/doc/ext/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst similarity index 100% rename from doc/ext/autosectionlabel.rst rename to doc/usage/extensions/autosectionlabel.rst diff --git a/doc/ext/autosummary.rst b/doc/usage/extensions/autosummary.rst similarity index 100% rename from doc/ext/autosummary.rst rename to doc/usage/extensions/autosummary.rst diff --git a/doc/ext/coverage.rst b/doc/usage/extensions/coverage.rst similarity index 100% rename from doc/ext/coverage.rst rename to doc/usage/extensions/coverage.rst diff --git a/doc/ext/doctest.rst b/doc/usage/extensions/doctest.rst similarity index 100% rename from doc/ext/doctest.rst rename to doc/usage/extensions/doctest.rst diff --git a/doc/ext/example_google.py b/doc/usage/extensions/example_google.py similarity index 100% rename from doc/ext/example_google.py rename to doc/usage/extensions/example_google.py diff --git a/doc/ext/example_google.rst b/doc/usage/extensions/example_google.rst similarity index 100% rename from doc/ext/example_google.rst rename to doc/usage/extensions/example_google.rst diff --git a/doc/ext/example_numpy.py b/doc/usage/extensions/example_numpy.py similarity index 100% rename from doc/ext/example_numpy.py rename to doc/usage/extensions/example_numpy.py diff --git a/doc/ext/example_numpy.rst b/doc/usage/extensions/example_numpy.rst similarity index 100% rename from doc/ext/example_numpy.rst rename to doc/usage/extensions/example_numpy.rst diff --git a/doc/ext/extlinks.rst b/doc/usage/extensions/extlinks.rst similarity index 100% rename from doc/ext/extlinks.rst rename to doc/usage/extensions/extlinks.rst diff --git a/doc/ext/githubpages.rst b/doc/usage/extensions/githubpages.rst similarity index 100% rename from doc/ext/githubpages.rst rename to doc/usage/extensions/githubpages.rst diff --git a/doc/ext/graphviz.rst b/doc/usage/extensions/graphviz.rst similarity index 100% rename from doc/ext/graphviz.rst rename to doc/usage/extensions/graphviz.rst diff --git a/doc/ext/ifconfig.rst b/doc/usage/extensions/ifconfig.rst similarity index 100% rename from doc/ext/ifconfig.rst rename to doc/usage/extensions/ifconfig.rst diff --git a/doc/ext/imgconverter.rst b/doc/usage/extensions/imgconverter.rst similarity index 100% rename from doc/ext/imgconverter.rst rename to doc/usage/extensions/imgconverter.rst diff --git a/doc/ext/thirdparty.rst b/doc/usage/extensions/index.rst similarity index 51% rename from doc/ext/thirdparty.rst rename to doc/usage/extensions/index.rst index 20dda9ff1..ae9639ee8 100644 --- a/doc/ext/thirdparty.rst +++ b/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 -publicly; just send a short message asking for write permissions. +repository. It is open for anyone who wants to maintain an extension publicly; +just send a short message asking for write permissions. There are also several extensions hosted elsewhere. The `Sphinx extension survey `__ and `awesome-sphinxdoc @@ -16,15 +57,13 @@ list (`join here `_). .. _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. -E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the -project root, put into :file:`conf.py`:: +Sphinx can find them. For example, if your extension ``foo.py`` lies in the +``exts`` subdirectory of the project root, put into :file:`conf.py`:: import sys, os diff --git a/doc/ext/inheritance.rst b/doc/usage/extensions/inheritance.rst similarity index 100% rename from doc/ext/inheritance.rst rename to doc/usage/extensions/inheritance.rst diff --git a/doc/ext/intersphinx.rst b/doc/usage/extensions/intersphinx.rst similarity index 100% rename from doc/ext/intersphinx.rst rename to doc/usage/extensions/intersphinx.rst diff --git a/doc/ext/linkcode.rst b/doc/usage/extensions/linkcode.rst similarity index 100% rename from doc/ext/linkcode.rst rename to doc/usage/extensions/linkcode.rst diff --git a/doc/ext/math.rst b/doc/usage/extensions/math.rst similarity index 100% rename from doc/ext/math.rst rename to doc/usage/extensions/math.rst diff --git a/doc/ext/napoleon.rst b/doc/usage/extensions/napoleon.rst similarity index 100% rename from doc/ext/napoleon.rst rename to doc/usage/extensions/napoleon.rst diff --git a/doc/ext/todo.rst b/doc/usage/extensions/todo.rst similarity index 100% rename from doc/ext/todo.rst rename to doc/usage/extensions/todo.rst diff --git a/doc/ext/viewcode.rst b/doc/usage/extensions/viewcode.rst similarity index 100% rename from doc/ext/viewcode.rst rename to doc/usage/extensions/viewcode.rst diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index e90b993c6..fabbf9905 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -318,12 +318,7 @@ features of intersphinx. More topics to be covered ------------------------- -- :doc:`Other extensions `: - - * :doc:`/ext/math`, - * :doc:`/ext/viewcode`, - * :doc:`/ext/doctest`, - * ... +- :doc:`Other extensions `: - Static files - :doc:`Selecting a theme ` - :doc:`/setuptools` diff --git a/setup.cfg b/setup.cfg index 091b59bbd..86f0be001 100644 --- a/setup.cfg +++ b/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