From 7e27e09493096a20c30702b410a24ab330ecea10 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 6 Feb 2018 11:25:43 +0000 Subject: [PATCH 1/4] doc: Rework "builders" document There are a number of cleanup items. - Some paragraphs are reworded or clarified - Semantic markup is added where possible - Everything is wrapped to ~80 characters A number of TODOs are inserted. These will be resolved separately. Signed-off-by: Stephen Finucane --- doc/builders.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/builders.rst b/doc/builders.rst index d968f209f..ee0aa0a33 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -1,7 +1,8 @@ .. _builders: -Available builders -================== +======== +Builders +======== .. module:: sphinx.builders :synopsis: Available built-in builder classes. @@ -75,8 +76,8 @@ The builder's "name" must be given to the **-b** command-line option of .. class:: QtHelpBuilder This builder produces the same output as the standalone HTML builder, but - also generates `Qt help`_ collection support files that allow - the Qt collection generator to compile them. + also generates `Qt help`_ collection support files that allow the Qt + collection generator to compile them. .. autoattribute:: name @@ -144,7 +145,8 @@ The builder's "name" must be given to the **-b** command-line option of .. versionchanged:: 1.5 - Since Sphinx-1.5, the epub3 builder is used for the default builder of epub. + Since Sphinx-1.5, the epub3 builder is used for the default builder of + epub. .. module:: sphinx.builders.latex .. class:: LaTeXBuilder @@ -159,12 +161,12 @@ The builder's "name" must be given to the **-b** command-line option of in a "minimal" TeX distribution installation. For example, on Ubuntu, the following packages need to be installed for successful PDF builds: - * texlive-latex-recommended - * texlive-fonts-recommended - * texlive-latex-extra - * latexmk (for ``make latexpdf`` on GNU/Linux and MacOS X) - * latex-xcolor (old Ubuntu) - * texlive-luatex, texlive-xetex (see :confval:`latex_engine`) + * ``texlive-latex-recommended`` + * ``texlive-fonts-recommended`` + * ``texlive-latex-extra`` + * ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X) + * ``latex-xcolor`` (old Ubuntu) + * ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`) The testing of Sphinx LaTeX is done on Ubuntu trusty with the above mentioned packages, which are from a TeXLive 2013 snapshot dated @@ -178,7 +180,7 @@ The builder's "name" must be given to the **-b** command-line option of Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This makes sure the needed number of runs is automatically executed to get the cross-references, bookmarks, indices, and tables of contents right. - + One can pass to ``latexmk`` options via the ``LATEXMKOPTS`` Makefile variable. For example: @@ -311,7 +313,6 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. The filename for the search index Sphinx generates. - See :ref:`serialization-details` for details about the output format. .. versionadded:: 0.5 From b595c4a45b3b19641dc4fbbb0ffa5f352ccdcf3d Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 20:52:13 +0000 Subject: [PATCH 2/4] doc: Add "builders" to usage guide This is placed in a directory as this document will eventually be split up. However, this is not the day to do this. Signed-off-by: Stephen Finucane --- doc/contents.rst | 2 +- doc/glossary.rst | 3 ++- doc/man/sphinx-build.rst | 6 +++--- doc/{builders.rst => usage/builders/index.rst} | 0 doc/usage/restructuredtext/basics.rst | 2 +- 5 files changed, 7 insertions(+), 6 deletions(-) rename doc/{builders.rst => usage/builders/index.rst} (100%) diff --git a/doc/contents.rst b/doc/contents.rst index 77dcf6c42..2da3cb979 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -12,10 +12,10 @@ Sphinx documentation contents usage/restructuredtext/index usage/markdown usage/configuration + usage/builders/index intro man/index - builders intl theming setuptools diff --git a/doc/glossary.rst b/doc/glossary.rst index 167edb8d4..c74409453 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -12,7 +12,8 @@ Glossary use the builder builders that e.g. check for broken links in the documentation, or build coverage information. - See :ref:`builders` for an overview over Sphinx's built-in builders. + See :doc:`/usage/builders/index` for an overview over Sphinx's built-in + builders. configuration directory The directory containing :file:`conf.py`. By default, this is the same as diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index fdd0d36c2..72235efad 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -86,8 +86,8 @@ Options Build compact pretty-printed "pseudo-XML" files displaying the internal structure of the intermediate document trees. - See :ref:`builders` for a list of all builders shipped with Sphinx. - Extensions can add their own builders. + See :doc:`/usage/builders/index` for a list of all builders shipped with + Sphinx. Extensions can add their own builders. .. _make_mode: @@ -96,7 +96,7 @@ Options Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module, which provides the same build functionality as a default :ref:`Makefile or Make.bat `. In addition to all Sphinx - :ref:`builders `, the following build pipelines are available: + :doc:`/usage/builders/index`, the following build pipelines are available: **latexpdf** Build LaTeX files and run them through :program:`pdflatex`, or as per diff --git a/doc/builders.rst b/doc/usage/builders/index.rst similarity index 100% rename from doc/builders.rst rename to doc/usage/builders/index.rst diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 3e1253544..1f36cdc40 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -444,7 +444,7 @@ candidates. For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Supported image types and choosing priority are defined at -:ref:`builders`. +:doc:`/usage/builders/index`. Note that image file names should not contain spaces. From 0b81af6a2eee5533e5c6c95097f2cca257f805e3 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 8 Jun 2018 17:27:13 +0100 Subject: [PATCH 3/4] doc: Rework "extensions" documents This is mostly spacing and other "niceness" fixes. Signed-off-by: Stephen Finucane --- doc/ext/autodoc.rst | 1 + doc/ext/autosectionlabel.rst | 1 + doc/ext/autosummary.rst | 2 -- doc/ext/coverage.rst | 2 -- doc/ext/doctest.rst | 1 - doc/ext/extlinks.rst | 1 - doc/ext/githubpages.rst | 2 -- doc/ext/graphviz.rst | 1 - doc/ext/imgconverter.rst | 22 ++++++++++++---------- doc/ext/inheritance.rst | 4 +++- doc/ext/intersphinx.rst | 13 ++++++++----- doc/ext/linkcode.rst | 4 ++++ doc/ext/napoleon.rst | 26 ++++++++++++-------------- doc/ext/todo.rst | 5 ++++- doc/ext/viewcode.rst | 14 +++++++------- 15 files changed, 52 insertions(+), 47 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 9064fe1b3..385254734 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -405,6 +405,7 @@ There are also new config values that you can set: .. versionadded:: 1.7 + Docstring preprocessing ----------------------- diff --git a/doc/ext/autosectionlabel.rst b/doc/ext/autosectionlabel.rst index f4a6322c3..20b15ca20 100644 --- a/doc/ext/autosectionlabel.rst +++ b/doc/ext/autosectionlabel.rst @@ -27,6 +27,7 @@ default. The ``autosectionlabel_prefix_document`` configuration variable can be used to make headings which appear multiple times but in different documents unique. + Configuration ------------- diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 46d8e4b56..008bc5613 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -25,7 +25,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: These files by default contain only the corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with templates. - .. rst:directive:: autosummary Insert a table that contains links to documented items, and a short summary @@ -59,7 +58,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` hooks as :mod:`~sphinx.ext.autodoc`. - **Options** * If you want the :rst:dir:`autosummary` table to also serve as a diff --git a/doc/ext/coverage.rst b/doc/ext/coverage.rst index 839478fe1..94d4c6fe4 100644 --- a/doc/ext/coverage.rst +++ b/doc/ext/coverage.rst @@ -4,7 +4,6 @@ .. module:: sphinx.ext.coverage :synopsis: Check Python modules and C API for coverage in the documentation. - This extension features one additional builder, the :class:`CoverageBuilder`. .. class:: CoverageBuilder @@ -14,7 +13,6 @@ This extension features one additional builder, the :class:`CoverageBuilder`. .. todo:: Write this section. - Several new configuration values can be used to specify what the builder should check: diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 62221bf04..341b7a9a7 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -165,7 +165,6 @@ a comma-separated list of group names. Output text. - The following is an example for the usage of the directives. The test via :rst:dir:`doctest` and the test via :rst:dir:`testcode` and :rst:dir:`testoutput` are equivalent. :: diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst index b809a740b..d818ba09b 100644 --- a/doc/ext/extlinks.rst +++ b/doc/ext/extlinks.rst @@ -7,7 +7,6 @@ .. versionadded:: 1.0 - This extension is meant to help with the common pattern of having many external links that point to URLs on one and the same site, e.g. links to bug trackers, version control web interfaces, or simply subpages in other websites. It does diff --git a/doc/ext/githubpages.rst b/doc/ext/githubpages.rst index 0cd76a2c9..f19666ef1 100644 --- a/doc/ext/githubpages.rst +++ b/doc/ext/githubpages.rst @@ -1,5 +1,3 @@ -.. highlight:: rest - :mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages ================================================================== diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index 8b9fff90b..f87f1a4b7 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -13,7 +13,6 @@ your documents. It adds these directives: - .. rst:directive:: graphviz Directive to embed graphviz code. The input code for ``dot`` is given as the diff --git a/doc/ext/imgconverter.rst b/doc/ext/imgconverter.rst index 322a9b5f3..5799fc3b3 100644 --- a/doc/ext/imgconverter.rst +++ b/doc/ext/imgconverter.rst @@ -1,28 +1,30 @@ -.. highlight:: rest - .. _sphinx.ext.imgconverter: -:mod:`sphinx.ext.imgconverter` -- A reference implementation for image converter using Imagemagick -================================================================================================== +:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick +=============================================================================== .. module:: sphinx.ext.imgconverter :synopsis: Convert images to appropriate format for builders .. versionadded:: 1.6 -This extension converts images in your document to appropriate format for builders. -For example, it allows you to use SVG images with LaTeX builder. +This extension converts images in your document to appropriate format for +builders. For example, it allows you to use SVG images with LaTeX builder. As a result, you don't mind what image format the builder supports. Internally, this extension uses Imagemagick_ to convert images. .. _Imagemagick: https://www.imagemagick.org/script/index.php -.. note:: Imagemagick rasterizes a SVG image on conversion. As a result, the image - becomes not scalable. To avoid that, please use other image converters - like sphinxcontrib-svg2pdfconverter_ (which uses Inkscape or rsvg-convert). +.. note:: + + Imagemagick rasterizes a SVG image on conversion. As a result, the image + becomes not scalable. To avoid that, please use other image converters like + `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or + ``rsvg-convert``). + +.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter -.. _sphinxcontrib-svg2pdfconverter: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter Configuration ------------- diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst index 0062a8afa..ef78d04fe 100644 --- a/doc/ext/inheritance.rst +++ b/doc/ext/inheritance.rst @@ -91,7 +91,9 @@ It adds this directive: .. versionchanged:: 1.7 Added ``top-classes`` option to limit the scope of inheritance graphs. -New config values are: + +Configuration +------------- .. confval:: inheritance_graph_attrs diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index b8ae104b3..cfda53e8f 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -38,8 +38,9 @@ Behind the scenes, this works as follows: specified individually, e.g. if the docs should be buildable without Internet access. -Configuring Intersphinx ------------------------ + +Configuration +------------- To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your :confval:`extensions` config value, and use these new config values to activate @@ -136,12 +137,14 @@ linking: exception is raised if the server has not issued a response for timeout seconds. + Showing all links of an Intersphinx mapping file ------------------------------------------------ -To show all Intersphinx links and their targets of an Intersphinx mapping file, run -``python -msphinx.ext.intersphinx url-or-path``. This is helpful when searching for the root cause of a broken -Intersphinx link in a documentation project. The following example prints the Intersphinx mapping of the Python 3 +To show all Intersphinx links and their targets of an Intersphinx mapping file, +run ``python -msphinx.ext.intersphinx url-or-path``. This is helpful when +searching for the root cause of a broken Intersphinx link in a documentation +project. The following example prints the Intersphinx mapping of the Python 3 documentation:: $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv diff --git a/doc/ext/linkcode.rst b/doc/ext/linkcode.rst index f00345fca..e65a0b780 100644 --- a/doc/ext/linkcode.rst +++ b/doc/ext/linkcode.rst @@ -16,6 +16,10 @@ found somewhere on the Internet. In your configuration, you need to specify a :confval:`linkcode_resolve` function that returns an URL based on the object. + +Configuration +------------- + .. confval:: linkcode_resolve This is a function ``linkcode_resolve(domain, info)``, diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst index 6c5f0d61a..b6c8d681b 100644 --- a/doc/ext/napoleon.rst +++ b/doc/ext/napoleon.rst @@ -1,5 +1,5 @@ :mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================================================================== .. module:: sphinx.ext.napoleon :synopsis: Support for NumPy and Google style docstrings @@ -8,8 +8,8 @@ .. versionadded:: 1.3 -Napoleon - *Marching toward legible docstrings* -=============================================== +Overview +-------- .. highlight:: text @@ -25,7 +25,7 @@ Are you tired of writing docstrings that look like this:: :returns: A buffered writable file descriptor :rtype: BufferedFileStorage -`ReStructuredText`_ is great, but it creates visually dense, hard to read +`reStructuredText`_ is great, but it creates visually dense, hard to read `docstrings`_. Compare the jumble above to the same thing rewritten according to the `Google Python Style Guide`_:: @@ -40,8 +40,8 @@ according to the `Google Python Style Guide`_:: Much more legible, no? -Napoleon is a :doc:`../extensions` that enables Sphinx to parse both `NumPy`_ -and `Google`_ style docstrings - the style recommended by `Khan Academy`_. +Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and +`Google`_ style docstrings - the style recommended by `Khan Academy`_. Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style docstrings and converts them to reStructuredText before Sphinx attempts to @@ -61,7 +61,7 @@ source code files. https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings Getting Started ---------------- +~~~~~~~~~~~~~~~ 1. After :doc:`setting up Sphinx ` to build your docs, enable napoleon in the Sphinx `conf.py` file:: @@ -77,7 +77,7 @@ Getting Started Docstrings ----------- +~~~~~~~~~~ Napoleon interprets every docstring that :mod:`autodoc ` can find, including docstrings on: ``modules``, ``classes``, ``attributes``, @@ -91,7 +91,7 @@ All standard reStructuredText formatting still works as expected. .. _Sections: Docstring Sections ------------------- +~~~~~~~~~~~~~~~~~~ All of the following section headers are supported: @@ -120,7 +120,7 @@ All of the following section headers are supported: * ``Yields`` Google vs NumPy ---------------- +~~~~~~~~~~~~~~~ Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The main difference between the two styles is that Google uses indention to @@ -188,7 +188,7 @@ not be mixed. Choose one style for your project and be consistent with it. Type Annotations ----------------- +~~~~~~~~~~~~~~~~ `PEP 484`_ introduced a standard way to express types in Python code. This is an alternative to expressing types directly in docstrings. @@ -242,7 +242,7 @@ Google style with types in docstrings:: Configuration -============= +------------- Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx `conf.py` file. Make @@ -271,8 +271,6 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`:: .. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt - - .. confval:: napoleon_google_docstring True to parse `Google style`_ docstrings. False to disable support diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst index 09abfa9b8..982005bd6 100644 --- a/doc/ext/todo.rst +++ b/doc/ext/todo.rst @@ -27,7 +27,10 @@ There are two additional directives when using this extension: documentation, if :confval:`todo_include_todos` is ``True``. -There is also an additional config value: +These can be configured as seen below. + +Configuration +------------- .. confval:: todo_include_todos diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index 87071144f..ea7d5d335 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -7,9 +7,8 @@ .. versionadded:: 1.0 - -This extension looks at your Python object descriptions (``.. class::``, -``.. function::`` etc.) and tries to find the source files where the objects are +This extension looks at your Python object descriptions (``.. class::``, ``.. +function::`` etc.) and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back @@ -33,14 +32,15 @@ This extension works only on HTML related builders like ``html``, ``singlehtml``. By default ``epub`` builder doesn't support this extension (see :confval:`viewcode_enable_epub`). -There is an additional config value: +Configuration +------------- .. confval:: viewcode_follow_imported_members If this is ``True``, viewcode extension will follow alias objects that - imported from another module such as functions, classes and attributes. - As side effects, this option - else they produce nothing. The default is ``True``. + imported from another module such as functions, classes and attributes. As + side effects, this option else they produce nothing. The default is + ``True``. .. versionadded:: 1.3 From d9ccc957173da20174271e6950988cff9e091a42 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 20:58:21 +0000 Subject: [PATCH 4/4] 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