diff --git a/.github/workflows/docutils-latest.yml b/.github/workflows/docutils-latest.yml index 91d9a4197f3..0e8029fc21b 100644 --- a/.github/workflows/docutils-latest.yml +++ b/.github/workflows/docutils-latest.yml @@ -21,8 +21,6 @@ jobs: python-version: 3 - name: Check Python version run: python --version - - name: Unpin docutils - run: sed -i -e "s/'docutils>=.*'/'docutils'/" setup.py - name: Install graphviz run: sudo apt-get install graphviz - name: Install dependencies diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 5e583d7b604..4a8deb00dc3 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -20,6 +20,6 @@ jobs: with: python-version: 3 - name: Install dependencies - run: pip install -U tox + run: python -m pip install -U tox pip - name: Run Tox run: tox -e ${{ matrix.tool }} diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1f798749ed2..d0b1f4d05da 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -2,6 +2,9 @@ name: CI on: [push, pull_request] +permissions: + contents: read + jobs: ubuntu: runs-on: ubuntu-18.04 diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index ac92ac7f35a..9d4c1a244cd 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -2,6 +2,9 @@ name: CI (node.js) on: [push, pull_request] +permissions: + contents: read + jobs: build: runs-on: ubuntu-latest diff --git a/AUTHORS b/AUTHORS index 713082e51a2..a35c27044f0 100644 --- a/AUTHORS +++ b/AUTHORS @@ -30,6 +30,7 @@ Contributors * Antonio Valentino -- qthelp builder, docstring inheritance * Antti Kaihola -- doctest extension (skipif option) * Barry Warsaw -- setup command improvements +* Ben Egan -- Napoleon improvements * Benjamin Peterson -- unittests * Blaise Laflamme -- pyramid theme * Bruce Mitchener -- Minor epub improvement diff --git a/CHANGES b/CHANGES index 82c87936c21..75a9ab0db8b 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,64 @@ +Release 5.2.1 (released Sep 24, 2022) +===================================== + +Bugs fixed +---------- + +* #10861: Always normalise the ``pycon3`` lexer to ``pycon``. +* Fix using ``sphinx.ext.autosummary`` with modules containing titles in the + module-level docstring. + +Release 5.2.0.post0 (released Sep 24, 2022) +=========================================== + +* Recreated source tarballs for Debian maintainers. + +Release 5.2.0 (released Sep 24, 2022) +===================================== + +Dependencies +------------ + +* #10356: Sphinx now uses declarative metadata with ``pyproject.toml`` to + create packages, using PyPA's ``flit`` project as a build backend. Patch by + Adam Turner. + +Deprecated +---------- + +* #10843: Support for HTML 4 output. Patch by Adam Turner. + +Features added +-------------- + +* #10738: napoleon: Add support for docstring types using 'of', like + ``type of type``. Example: ``tuple of int``. +* #10286: C++, support requires clauses not just between the template + parameter lists and the declaration. +* #10755: linkcheck: Check the source URL of raw directives that use the ``url`` + option. +* #10781: Allow :rst:role:`ref` role to be used with definitions and fields. +* #10717: HTML Search: Increase priority for full title and + subtitle matches in search results +* #10718: HTML Search: Save search result score to the HTML element for debugging +* #10673: Make toctree accept 'genindex', 'modindex' and 'search' docnames +* #6316, #10804: Add domain objects to the table of contents. Patch by Adam Turner +* #6692: HTML Search: Include explicit :rst:dir:`index` directive index entries + in the search index and search results. Patch by Adam Turner +* #10816: imgmath: Allow embedding images in HTML as base64 +* #10854: HTML Search: Use browser localstorage for highlight control, stop + storing highlight parameters in URL query strings. Patch by Adam Turner. + +Bugs fixed +---------- + +* #10723: LaTeX: 5.1.0 has made the 'sphinxsetup' ``verbatimwithframe=false`` + become without effect. +* #10257: C++, ensure consistent non-specialization template argument + representation. +* #10729: C++, fix parsing of certain non-type template parameter packs. +* #10715: Revert #10520: "Fix" use of sidebar classes in ``agogo.css_t`` + Release 5.1.1 (released Jul 26, 2022) ===================================== @@ -58,8 +119,8 @@ Bugs fixed * #10506: LaTeX: build error if highlighting inline code role in figure caption (refs: #10251) * #10634: Make -P (pdb) option work better with exceptions triggered from events -* #10031: py domain: Fix spurious whitespace in unparsing various operators (``+``, - ``-``, ``~``, and ``**``). Patch by Adam Turner. +* #10550: py domain: Fix spurious whitespace in unparsing various operators (``+``, + ``-``, ``~``, and ``**``). Patch by Adam Turner (refs: #10551). * #10460: logging: Always show node source locations as absolute paths. * HTML Search: HTML tags are displayed as a part of object name * HTML Search: search snipets should not be folded diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 7c2f852a81c..00000000000 --- a/MANIFEST.in +++ /dev/null @@ -1,33 +0,0 @@ -include README.rst -include LICENSE -include AUTHORS -include CHANGES -include CHANGES.old -include CODE_OF_CONDUCT -include CONTRIBUTING.rst -include EXAMPLES - -include babel.cfg -include Makefile -include sphinx-autogen.py -include sphinx-build.py -include sphinx-quickstart.py -include sphinx-apidoc.py -include tox.ini -include sphinx/locale/.tx/config -include sphinx/py.typed - -recursive-include sphinx/templates * -recursive-include sphinx/texinputs * -recursive-include sphinx/texinputs_win * -recursive-include sphinx/themes * -recursive-include sphinx/locale *.js *.pot *.po *.mo -recursive-include sphinx/search/non-minified-js *.js -recursive-include sphinx/search/minified-js *.js -recursive-include sphinx/ext/autosummary/templates * -recursive-include tests * -recursive-include utils * - -recursive-include doc * -prune doc/_build -prune sphinx/locale/.tx diff --git a/Makefile b/Makefile index 9213820b70b..4602246d9cf 100644 --- a/Makefile +++ b/Makefile @@ -74,7 +74,7 @@ covertest: .PHONY: build build: - @$(PYTHON) setup.py build + @$(PYTHON) -m build . .PHONY: docs docs: diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index 4cf1df80e67..397c1f7893e 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -131,7 +131,7 @@ div.footer { background-color: var(--colour-sphinx-blue); color: #ccc; text-shadow: 0 0 .2px rgba(255, 255, 255, 0.8); - padding: 3px 8px 3px 0; + padding: 3px 8px 3px 8px; clear: both; font-size: 0.8em; } @@ -273,7 +273,7 @@ div.quotebar { margin-left: 1em; } -blockquote { +blockquote.epigraph { font-size: 1.5em; padding-left: 1rem; margin-left: 0; diff --git a/doc/conf.py b/doc/conf.py index a721508debf..eafa42a7d1a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,6 +48,7 @@ ('develop.xhtml', 'Sphinx development')] epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', '_static/jquery.js', '_static/searchtools.js', + '_static/sphinx_highlight.js', '_static/underscore.js', '_static/basic.css', '_static/language_data.js', 'search.html', '_static/websupport.js'] diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py index 7af8af90dca..8dc53fdd6dc 100644 --- a/doc/development/tutorials/examples/recipe.py +++ b/doc/development/tutorials/examples/recipe.py @@ -120,8 +120,7 @@ def get_full_qualified_name(self, node): return '{}.{}'.format('recipe', node.arguments[0]) def get_objects(self): - for obj in self.data['recipes']: - yield(obj) + yield from self.data['recipes'] def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst index 2273330f14a..8940e3dfd8c 100644 --- a/doc/development/tutorials/helloworld.rst +++ b/doc/development/tutorials/helloworld.rst @@ -105,7 +105,7 @@ Sphinx. :linenos: :lines: 12- -The simplest thing you can do it call the :meth:`~Sphinx.add_directive` method, +The simplest thing you can do is to call the :meth:`~Sphinx.add_directive` method, which is what we've done here. For this particular call, the first argument is the name of the directive itself as used in a reST file. In this case, we would use ``helloworld``. For example: diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 18b0e6d04e3..8c850ceb6b4 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -22,6 +22,11 @@ The following is a list of deprecated interfaces. - (will be) Removed - Alternatives + * - HTML 4 support + - 5.2 + - 7.0 + - N/A + * - ``sphinx.util.path_stabilize`` - 5.1 - 7.0 diff --git a/doc/extdev/domainapi.rst b/doc/extdev/domainapi.rst index a666fc06d86..d70b5db751d 100644 --- a/doc/extdev/domainapi.rst +++ b/doc/extdev/domainapi.rst @@ -17,6 +17,7 @@ Domain API .. autoclass:: ObjectDescription :members: + :private-members: _toc_entry_name, _object_hierarchy_parts Python Domain ------------- diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 92281eb9370..014a806e5d5 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -97,49 +97,49 @@ in which a Sphinx project is built: this works in several phases. **Phase 0: Initialization** - In this phase, almost nothing of interest to us happens. The source - directory is searched for source files, and extensions are initialized. - Should a stored build environment exist, it is loaded, otherwise a new one is - created. +In this phase, almost nothing of interest to us happens. The source +directory is searched for source files, and extensions are initialized. +Should a stored build environment exist, it is loaded, otherwise a new one is +created. **Phase 1: Reading** - In Phase 1, all source files (and on subsequent builds, those that are new or - changed) are read and parsed. This is the phase where directives and roles - are encountered by docutils, and the corresponding code is executed. The - output of this phase is a *doctree* for each source file; that is a tree of - docutils nodes. For document elements that aren't fully known until all - existing files are read, temporary nodes are created. +In Phase 1, all source files (and on subsequent builds, those that are new or +changed) are read and parsed. This is the phase where directives and roles +are encountered by docutils, and the corresponding code is executed. The +output of this phase is a *doctree* for each source file; that is a tree of +docutils nodes. For document elements that aren't fully known until all +existing files are read, temporary nodes are created. - There are nodes provided by docutils, which are documented `in the docutils - documentation `__. - Additional nodes are provided by Sphinx and :ref:`documented here `. +There are nodes provided by docutils, which are documented `in the docutils +documentation `__. +Additional nodes are provided by Sphinx and :ref:`documented here `. - During reading, the build environment is updated with all meta- and cross - reference data of the read documents, such as labels, the names of headings, - described Python objects and index entries. This will later be used to - replace the temporary nodes. +During reading, the build environment is updated with all meta- and cross +reference data of the read documents, such as labels, the names of headings, +described Python objects and index entries. This will later be used to +replace the temporary nodes. - The parsed doctrees are stored on the disk, because it is not possible to - hold all of them in memory. +The parsed doctrees are stored on the disk, because it is not possible to +hold all of them in memory. **Phase 2: Consistency checks** - Some checking is done to ensure no surprises in the built documents. +Some checking is done to ensure no surprises in the built documents. **Phase 3: Resolving** - Now that the metadata and cross-reference data of all existing documents is - known, all temporary nodes are replaced by nodes that can be converted into - output using components called transforms. For example, links are created - for object references that exist, and simple literal nodes are created for - those that don't. +Now that the metadata and cross-reference data of all existing documents is +known, all temporary nodes are replaced by nodes that can be converted into +output using components called transforms. For example, links are created +for object references that exist, and simple literal nodes are created for +those that don't. **Phase 4: Writing** - This phase converts the resolved doctrees to the desired output format, such - as HTML or LaTeX. This happens via a so-called docutils writer that visits - the individual nodes of each doctree and produces some output in the process. +This phase converts the resolved doctrees to the desired output format, such +as HTML or LaTeX. This happens via a so-called docutils writer that visits +the individual nodes of each doctree and produces some output in the process. .. note:: diff --git a/doc/latex.rst b/doc/latex.rst index c46ab6e29b6..7fa90fe8922 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -407,12 +407,16 @@ Keys that don't need to be overridden unless in special cases are: ``'geometry'`` "geometry" package inclusion, the default definition is: - ``'\\usepackage{geometry}'`` + .. code:: latex + + '\\usepackage{geometry}' with an additional ``[dvipdfm]`` for Japanese documents. The Sphinx LaTeX style file executes: - ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}`` + .. code:: latex + + \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry} which can be customized via corresponding :ref:`'sphinxsetup' options `. @@ -1296,6 +1300,12 @@ Macros ``\sphinxtableofcontentshook``. This macro is also executed by the ``'howto'`` docclass, but defaults to empty with it. + .. hint:: + + If adding to preamble the loading of ``tocloft`` package, also add to + preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset + ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization. + - ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` :confval:`latex_elements` key. Defined in the class files :file:`sphinxmanual.cls` and diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index cc62fd4284e..76b68c3c157 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -192,7 +192,7 @@ contents: steps: - uses: actions/checkout@v3 - name: Build HTML - uses: ammaraskar/sphinx-action@0.4 + uses: ammaraskar/sphinx-action@master - name: Upload artifacts uses: actions/upload-artifact@v3 with: diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 9e6230cd2db..5866b0e2977 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -14,12 +14,12 @@ This file (containing Python code) is called the "build configuration file" and contains (almost) all configuration needed to customize Sphinx input and output behavior. - An optional file `docutils.conf`_ can be added to the configuration - directory to adjust `Docutils`_ configuration if not otherwise overridden or - set by Sphinx. +An optional file `docutils.conf`_ can be added to the configuration +directory to adjust `Docutils`_ configuration if not otherwise overridden or +set by Sphinx. - .. _`docutils`: https://docutils.sourceforge.io/ - .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html +.. _`docutils`: https://docutils.sourceforge.io/ +.. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html The configuration file is executed as Python code at build time (using :func:`importlib.import_module`, and with the current directory set to its @@ -419,9 +419,9 @@ General configuration :literal:`:manpage:`man(1)`` role will link to . The patterns available are: - * ``page`` - the manual page (``man``) - * ``section`` - the manual section (``1``) - * ``path`` - the original manual page and section specified (``man(1)``) + * ``page`` - the manual page (``man``) + * ``section`` - the manual section (``1``) + * ``path`` - the original manual page and section specified (``man(1)``) This also supports manpages specified as ``man.1``. @@ -678,6 +678,24 @@ General configuration :term:`object` names (for object types where a "module" of some kind is defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``. +.. confval:: toc_object_entries_show_parents + + A string that determines how domain objects (e.g. functions, classes, + attributes, etc.) are displayed in their table of contents entry. + + Use ``domain`` to allow the domain to determine the appropriate number of + parents to show. For example, the Python domain would show ``Class.method()`` + and ``function()``, leaving out the ``module.`` level of parents. + This is the default setting. + + Use ``hide`` to only show the name of the element without any parents + (i.e. ``method()``). + + Use ``all`` to show the fully-qualified name for the object + (i.e. ``module.Class.method()``), displaying all parents. + + .. versionadded:: 5.2 + .. confval:: show_authors A boolean that decides whether :rst:dir:`codeauthor` and diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 655d368a7c2..4e2fa136fb5 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -48,14 +48,14 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: produces a table like this: - .. currentmodule:: sphinx + .. currentmodule:: sphinx - .. autosummary:: + .. autosummary:: - environment.BuildEnvironment - util.relative_uri + environment.BuildEnvironment + util.relative_uri - .. currentmodule:: sphinx.ext.autosummary + .. currentmodule:: sphinx.ext.autosummary Autosummary preprocesses the docstrings and signatures with the same :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 62630608993..9ce3efe4f56 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -133,6 +133,12 @@ are built: elements (cf the `dvisvgm FAQ`_). This option is used only when ``imgmath_image_format`` is ``'svg'``. +.. confval:: imgmath_embed + + Default: ``False``. If true, encode LaTeX output images within HTML files + (base64 encoded) and do not save separate png/svg files to disk. + + .. versionadded:: 5.2 :mod:`sphinx.ext.mathjax` -- Render math via JavaScript ------------------------------------------------------- diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index 59ecad890c3..2c178d853a4 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -94,38 +94,38 @@ Docstring Sections All of the following section headers are supported: - * ``Args`` *(alias of Parameters)* - * ``Arguments`` *(alias of Parameters)* - * ``Attention`` - * ``Attributes`` - * ``Caution`` - * ``Danger`` - * ``Error`` - * ``Example`` - * ``Examples`` - * ``Hint`` - * ``Important`` - * ``Keyword Args`` *(alias of Keyword Arguments)* - * ``Keyword Arguments`` - * ``Methods`` - * ``Note`` - * ``Notes`` - * ``Other Parameters`` - * ``Parameters`` - * ``Return`` *(alias of Returns)* - * ``Returns`` - * ``Raise`` *(alias of Raises)* - * ``Raises`` - * ``References`` - * ``See Also`` - * ``Tip`` - * ``Todo`` - * ``Warning`` - * ``Warnings`` *(alias of Warning)* - * ``Warn`` *(alias of Warns)* - * ``Warns`` - * ``Yield`` *(alias of Yields)* - * ``Yields`` +* ``Args`` *(alias of Parameters)* +* ``Arguments`` *(alias of Parameters)* +* ``Attention`` +* ``Attributes`` +* ``Caution`` +* ``Danger`` +* ``Error`` +* ``Example`` +* ``Examples`` +* ``Hint`` +* ``Important`` +* ``Keyword Args`` *(alias of Keyword Arguments)* +* ``Keyword Arguments`` +* ``Methods`` +* ``Note`` +* ``Notes`` +* ``Other Parameters`` +* ``Parameters`` +* ``Return`` *(alias of Returns)* +* ``Returns`` +* ``Raise`` *(alias of Raises)* +* ``Raises`` +* ``References`` +* ``See Also`` +* ``Tip`` +* ``Todo`` +* ``Warning`` +* ``Warnings`` *(alias of Warning)* +* ``Warn`` *(alias of Warns)* +* ``Warns`` +* ``Yield`` *(alias of Yields)* +* ``Yields`` Google vs NumPy ~~~~~~~~~~~~~~~ @@ -182,8 +182,6 @@ tends to use more horizontal space. Google style tends to be easier to read for short and simple docstrings, whereas NumPy style tends be easier to read for long and in-depth docstrings. -The `Khan Academy`_ recommends using Google style. - The choice between styles is largely aesthetic, but the two styles should not be mixed. Choose one style for your project and be consistent with it. diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 3e7745a27e0..3ce8bb91314 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -208,9 +208,9 @@ You can read more about them in the `Python Packaging User Guide`_. Note that in some Linux distributions, such as Debian and Ubuntu, this might require an extra installation step as follows. - .. code-block:: console + .. code-block:: console - $ apt-get install python3-venv + $ apt-get install python3-venv Docker ------ diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 0a373e64662..397416a8907 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -137,11 +137,15 @@ declarations: This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the - package name). It does not create content (like e.g. :rst:dir:`py:class` - does). + package name). A description of the module such as the docstring can be + placed in the body of the directive. This directive will also cause an entry in the global module index. + .. versionchanged:: 5.2 + + Module directives support body content. + .. rubric:: options .. rst:directive:option:: platform: platforms @@ -165,6 +169,8 @@ declarations: Mark a module as deprecated; it will be designated as such in various locations then. + + .. rst:directive:: .. py:currentmodule:: name This directive tells Sphinx that the classes, functions etc. documented from @@ -516,7 +522,8 @@ For functions with optional parameters that don't have default values (typically functions implemented in C extension modules without keyword argument support), you can use brackets to specify the optional parts: - .. py:function:: compile(source[, filename[, symbol]]) +.. py:function:: compile(source[, filename[, symbol]]) + :noindex: It is customary to put the opening bracket before the comma. @@ -572,20 +579,20 @@ explained by an example:: This will render like this: - .. py:function:: send_message(sender, recipient, message_body, [priority=1]) - :noindex: +.. py:function:: send_message(sender, recipient, message_body, [priority=1]) + :noindex: - Send a message to a recipient + Send a message to a recipient - :param str sender: The person sending the message - :param str recipient: The recipient of the message - :param str message_body: The body of the message - :param priority: The priority of the message, can be a number 1-5 - :type priority: integer or None - :return: the message id - :rtype: int - :raises ValueError: if the message_body exceeds 160 characters - :raises TypeError: if the message_body is not a basestring + :param str sender: The person sending the message + :param str recipient: The recipient of the message + :param str message_body: The body of the message + :param priority: The priority of the message, can be a number 1-5 + :type priority: integer or None + :return: the message id + :rtype: int + :raises ValueError: if the message_body exceeds 160 characters + :raises TypeError: if the message_body is not a basestring It is also possible to combine parameter type and description, if the type is a single word, like this:: @@ -855,12 +862,16 @@ Example:: This will be rendered as: .. c:struct:: Data + :noindexentry: .. c:union:: @data + :noindexentry: .. c:var:: int a + :noindexentry: .. c:var:: double b + :noindexentry: Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. @@ -942,8 +953,10 @@ Inline Expressions and Types will be rendered as follows: .. c:var:: int a = 42 + :noindexentry: .. c:function:: int f(int i) + :noindexentry: An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). @@ -1153,19 +1166,23 @@ visibility statement (``public``, ``private`` or ``protected``). The example are rendered as follows. .. cpp:type:: std::vector MyList + :noindex: A typedef-like declaration of a type. .. cpp:type:: MyContainer::const_iterator + :noindex: Declaration of a type alias with unspecified type. .. cpp:type:: MyType = std::unordered_map + :noindex: Declaration of a type alias. .. cpp:type:: template \ MyContainer = std::vector + :noindex: .. rst:directive:: .. cpp:enum:: unscoped enum declaration .. cpp:enum-struct:: scoped enum declaration @@ -1292,12 +1309,16 @@ Example:: This will be rendered as: .. cpp:class:: Data + :noindexentry: .. cpp:union:: @data + :noindexentry: .. cpp:var:: int a + :noindexentry: .. cpp:var:: double b + :noindexentry: Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. @@ -1403,10 +1424,12 @@ introduction` instead of a template parameter list:: They are rendered as follows. .. cpp:function:: std::Iterator{It} void advance(It &it) + :noindexentry: A function template with a template parameter constrained to be an Iterator. .. cpp:class:: std::LessThanComparable{T} MySortedContainer + :noindexentry: A class template with a template parameter constrained to be LessThanComparable. @@ -1436,8 +1459,10 @@ Inline Expressions and Types will be rendered as follows: .. cpp:var:: int a = 42 + :noindexentry: .. cpp:function:: int f(int i) + :noindexentry: An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). @@ -1826,6 +1851,9 @@ The JavaScript domain (name **js**) provides the following directives: current module name. .. versionadded:: 1.6 + .. versionchanged:: 5.2 + + Module directives support body content. .. rst:directive:: .. js:function:: name(signature) @@ -1849,15 +1877,16 @@ The JavaScript domain (name **js**) provides the following directives: This is rendered as: - .. js:function:: $.getJSON(href, callback[, errback]) + .. js:function:: $.getJSON(href, callback[, errback]) + :noindex: - :param string href: An URI to the location of the resource. - :param callback: Gets called with the object. - :param errback: - Gets called in case the request fails. And a lot of other - text so we need multiple lines. - :throws SomeError: For whatever reason in that case. - :returns: Something. + :param string href: An URI to the location of the resource. + :param callback: Gets called with the object. + :param errback: + Gets called in case the request fails. And a lot of other + text so we need multiple lines. + :throws SomeError: For whatever reason in that case. + :returns: Something. .. rst:directive:: .. js:method:: name(signature) @@ -1878,10 +1907,11 @@ The JavaScript domain (name **js**) provides the following directives: This is rendered as: - .. js:class:: MyAnimal(name[, age]) + .. js:class:: MyAnimal(name[, age]) + :noindex: - :param string name: The name of the animal - :param number age: an optional age for the animal + :param string name: The name of the animal + :param number age: an optional age for the animal .. rst:directive:: .. js:data:: name @@ -1924,13 +1954,15 @@ The reStructuredText domain (name **rst**) provides the following directives: will be rendered as: - .. rst:directive:: foo + .. rst:directive:: foo + :noindex: - Foo description. + Foo description. - .. rst:directive:: .. bar:: baz + .. rst:directive:: .. bar:: baz + :noindex: - Bar description. + Bar description. .. rst:directive:: .. rst:directive:option:: name @@ -1946,12 +1978,14 @@ The reStructuredText domain (name **rst**) provides the following directives: will be rendered as: - .. rst:directive:: toctree - :noindex: + .. rst:directive:: toctree + :noindex: - .. rst:directive:option:: caption: caption of ToC + .. rst:directive:option:: caption: caption of ToC + :noindex: - .. rst:directive:option:: glob + .. rst:directive:option:: glob + :noindex: .. rubric:: options @@ -1979,9 +2013,10 @@ The reStructuredText domain (name **rst**) provides the following directives: will be rendered as: - .. rst:role:: foo + .. rst:role:: foo + :noindex: - Foo description. + Foo description. .. _rst-roles: diff --git a/karma.conf.js b/karma.conf.js index 082584cf7b9..8a18e80ba7a 100644 --- a/karma.conf.js +++ b/karma.conf.js @@ -15,8 +15,10 @@ module.exports = function(config) { // list of files / patterns to load in the browser files: [ + 'tests/js/documentation_options.js', 'sphinx/themes/basic/static/doctools.js', 'sphinx/themes/basic/static/searchtools.js', + 'sphinx/themes/basic/static/sphinx_highlight.js', 'tests/js/*.js' ], diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000000..14ca5d092be --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,221 @@ +[build-system] +requires = ["flit_core>=3.7"] +build-backend = "flit_core.buildapi" + +# project metadata +[project] +name = "Sphinx" +description = "Python documentation generator" +readme = "README.rst" +urls.Changelog = "https://www.sphinx-doc.org/en/master/changes.html" +urls.Code = "https://github.com/sphinx-doc/sphinx" +urls.Download = "https://pypi.org/project/Sphinx/" +urls.Homepage = "https://www.sphinx-doc.org/" +urls."Issue tracker" = "https://github.com/sphinx-doc/sphinx/issues" +license.text = "BSD" +requires-python = ">=3.6" + +# Classifiers list: https://pypi.org/classifiers/ +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Environment :: Console", + "Environment :: Web Environment", + "Intended Audience :: Developers", + "Intended Audience :: Education", + "Intended Audience :: End Users/Desktop", + "Intended Audience :: Science/Research", + "Intended Audience :: System Administrators", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.6", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: Implementation :: CPython", + "Programming Language :: Python :: Implementation :: PyPy", + "Framework :: Setuptools Plugin", + "Framework :: Sphinx", + "Framework :: Sphinx :: Extension", + "Framework :: Sphinx :: Theme", + "Topic :: Documentation", + "Topic :: Documentation :: Sphinx", + "Topic :: Internet :: WWW/HTTP :: Site Management", + "Topic :: Printing", + "Topic :: Software Development", + "Topic :: Software Development :: Documentation", + "Topic :: Text Processing", + "Topic :: Text Processing :: General", + "Topic :: Text Processing :: Indexing", + "Topic :: Text Processing :: Markup", + "Topic :: Text Processing :: Markup :: HTML", + "Topic :: Text Processing :: Markup :: LaTeX", + "Topic :: Utilities", +] +dependencies = [ + "sphinxcontrib-applehelp", + "sphinxcontrib-devhelp", + "sphinxcontrib-jsmath", + "sphinxcontrib-htmlhelp>=2.0.0", + "sphinxcontrib-serializinghtml>=1.1.5", + "sphinxcontrib-qthelp", + "Jinja2>=3.0", + "Pygments>=2.12", + "docutils>=0.14,<0.20", + "snowballstemmer>=2.0", + "babel>=2.9", + "alabaster>=0.7,<0.8", + "imagesize>=1.3", + "requests>=2.5.0", + "packaging>=21.0", + "importlib-metadata>=4.8; python_version < '3.10'", + "colorama>=0.4.5; sys_platform == 'win32'", +] +dynamic = ["version"] + +[project.optional-dependencies] +docs = [ + "sphinxcontrib-websupport", +] +lint = [ + "flake8>=3.5.0", + "flake8-comprehensions", + "flake8-bugbear", + "flake8-simplify", + "isort", + "mypy>=0.971", + "sphinx-lint", + "docutils-stubs", + "types-typed-ast", + "types-requests", +] +test = [ + "pytest>=4.6", + "html5lib", + "typed_ast; python_version < '3.8'", + "cython", +] + +[[project.authors]] +name = "Georg Brandl" +email = "georg@python.org" + +[project.scripts] +sphinx-build = "sphinx.cmd.build:main" +sphinx-quickstart = "sphinx.cmd.quickstart:main" +sphinx-apidoc = "sphinx.ext.apidoc:main" +sphinx-autogen = "sphinx.ext.autosummary.generate:main" + +[project.entry-points."distutils.commands"] +build_sphinx = 'sphinx.setup_command:BuildDoc' + +[tool.flit.module] +name = "sphinx" + +[tool.flit.sdist] +include = [ + "LICENSE", + "AUTHORS", + "CHANGES", + # Documentation + "doc/", + "CODE_OF_CONDUCT", # used as an include in the Documentation + "EXAMPLES", # used as an include in the Documentation + # Tests + "tests/", + "tox.ini", + # Utilities + "utils/", + "babel.cfg", +] +exclude = [ + "doc/_build", +] + +[tool.isort] +line_length = 95 + +[tool.mypy] +check_untyped_defs = true +disallow_incomplete_defs = true +follow_imports = "skip" +ignore_missing_imports = true +no_implicit_optional = true +python_version = "3.6" +show_column_numbers = true +show_error_codes = true +show_error_context = true +strict_optional = true +warn_redundant_casts = true +warn_unused_ignores = true +disallow_any_generics = true + +[[tool.mypy.overrides]] +module = [ + "sphinx.application", + "sphinx.builders", + "sphinx.builders.html", + "sphinx.builders.latex", + "sphinx.builders.linkcheck", + "sphinx.directives.code", + "sphinx.domains.*", + "sphinx.environment", + "sphinx.environment.adapters.toctree", + "sphinx.environment.adapters.indexentries", + "sphinx.ext.*", + "sphinx.pycode.parser", + "sphinx.registry", + "sphinx.setup_command", + "sphinx.testing.util", + "sphinx.transforms.i18n", + "sphinx.transforms.post_transforms.images", + "sphinx.util.cfamily", + "sphinx.util.docfields", + "sphinx.util.docutils", + "sphinx.util.nodes", + "sphinx.util.typing", + "sphinx.writers.latex", + "sphinx.writers.text", + "sphinx.writers.xml" +] +strict_optional = false + +[[tool.mypy.overrides]] +module = [ + "sphinx.application", + "sphinx.builders.*", + "sphinx.cmd.*", + "sphinx.config", + "sphinx.deprecation", + "sphinx.domains.*", + "sphinx.environment.*", + "sphinx.events", + "sphinx.ext.*", + "sphinx.highlighting", + "sphinx.jinja2glue", + "sphinx.locale", + "sphinx.pycode.*", + "sphinx.registry", + "sphinx.roles", + "sphinx.search.*", + "sphinx.testing.*", + "sphinx.util.*", + "sphinx.writers.*", +] +disallow_any_generics = false + +[tool.pytest.ini_options] +filterwarnings = [ + "all", + "ignore::DeprecationWarning:docutils.io", + "ignore::DeprecationWarning:pyximport.pyximport", + "ignore::ImportWarning:importlib._bootstrap", +] +markers = [ + "apidoc", + "setup_command", +] +testpaths = ["tests"] diff --git a/setup.cfg b/setup.cfg index 1c193cd266b..8c2224b22c7 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,51 +1,12 @@ -[metadata] -license_files = LICENSE - -[egg_info] -tag_build = .dev -tag_date = true - -[aliases] -release = egg_info -Db '' -upload = upload --sign --identity=36580288 - [flake8] max-line-length = 95 -ignore = E116,E241,E251,E741,W504,I101,B006,B023 +ignore = E116,E241,E251,E741,W504,I101,B006,B023,SIM102,SIM103,SIM105,SIM110,SIM113,SIM114,SIM115,SIM117,SIM223,SIM300,SIM401,SIM904,SIM905,SIM907 exclude = .git,.tox,.venv,tests/roots/*,build/*,doc/_build/*,sphinx/search/*,doc/usage/extensions/example*.py application-import-names = sphinx import-order-style = smarkets per-file-ignores = tests/*: E501 -[isort] -line_length = 95 - -[mypy] -python_version = 3.6 -disallow_incomplete_defs = True -show_column_numbers = True -show_error_context = True -show_error_codes = true -ignore_missing_imports = True -follow_imports = skip -check_untyped_defs = True -warn_unused_ignores = True -strict_optional = False -no_implicit_optional = True -warn_redundant_casts = True - -[tool:pytest] -filterwarnings = - all - ignore::DeprecationWarning:docutils.io - ignore::DeprecationWarning:pyximport.pyximport - ignore::ImportWarning:importlib._bootstrap -markers = - apidoc - setup_command -testpaths = tests - [coverage:run] branch = True parallel = True diff --git a/setup.py b/setup.py deleted file mode 100644 index 930a20fcbde..00000000000 --- a/setup.py +++ /dev/null @@ -1,136 +0,0 @@ -import sys - -from setuptools import find_packages, setup - -import sphinx - -with open('README.rst', encoding='utf-8') as f: - long_desc = f.read() - -if sys.version_info < (3, 6): - print('ERROR: Sphinx requires at least Python 3.6 to run.') - sys.exit(1) - -install_requires = [ - 'sphinxcontrib-applehelp', - 'sphinxcontrib-devhelp', - 'sphinxcontrib-jsmath', - 'sphinxcontrib-htmlhelp>=2.0.0', - 'sphinxcontrib-serializinghtml>=1.1.5', - 'sphinxcontrib-qthelp', - 'Jinja2>=2.3', - 'Pygments>=2.0', - 'docutils>=0.14,<0.20', - 'snowballstemmer>=1.1', - 'babel>=1.3', - 'alabaster>=0.7,<0.8', - 'imagesize', - 'requests>=2.5.0', - 'packaging', - "importlib-metadata>=4.4; python_version < '3.10'", -] - -extras_require = { - # Environment Marker works for wheel 0.24 or later - ':sys_platform=="win32"': [ - 'colorama>=0.3.5', - ], - 'docs': [ - 'sphinxcontrib-websupport', - ], - 'lint': [ - 'flake8>=3.5.0', - 'flake8-comprehensions', - 'flake8-bugbear', - 'isort', - 'mypy>=0.971', - 'sphinx-lint', - 'docutils-stubs', - "types-typed-ast", - "types-requests", - ], - 'test': [ - 'pytest>=4.6', - 'html5lib', - "typed_ast; python_version < '3.8'", - 'cython', - ], -} - -setup( - name='Sphinx', - version=sphinx.__version__, - url='https://www.sphinx-doc.org/', - download_url='https://pypi.org/project/Sphinx/', - license='BSD', - author='Georg Brandl', - author_email='georg@python.org', - description='Python documentation generator', - long_description=long_desc, - long_description_content_type='text/x-rst', - project_urls={ - "Code": "https://github.com/sphinx-doc/sphinx", - "Changelog": "https://www.sphinx-doc.org/en/master/changes.html", - "Issue tracker": "https://github.com/sphinx-doc/sphinx/issues", - }, - zip_safe=False, - classifiers=[ - 'Development Status :: 5 - Production/Stable', - 'Environment :: Console', - 'Environment :: Web Environment', - 'Intended Audience :: Developers', - 'Intended Audience :: Education', - 'Intended Audience :: End Users/Desktop', - 'Intended Audience :: Science/Research', - 'Intended Audience :: System Administrators', - 'License :: OSI Approved :: BSD License', - 'Operating System :: OS Independent', - 'Programming Language :: Python', - 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3 :: Only', - 'Programming Language :: Python :: 3.6', - 'Programming Language :: Python :: 3.7', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', - 'Programming Language :: Python :: 3.10', - 'Programming Language :: Python :: Implementation :: CPython', - 'Programming Language :: Python :: Implementation :: PyPy', - 'Framework :: Setuptools Plugin', - 'Framework :: Sphinx', - 'Framework :: Sphinx :: Extension', - 'Framework :: Sphinx :: Theme', - 'Topic :: Documentation', - 'Topic :: Documentation :: Sphinx', - 'Topic :: Internet :: WWW/HTTP :: Site Management', - 'Topic :: Printing', - 'Topic :: Software Development', - 'Topic :: Software Development :: Documentation', - 'Topic :: Text Processing', - 'Topic :: Text Processing :: General', - 'Topic :: Text Processing :: Indexing', - 'Topic :: Text Processing :: Markup', - 'Topic :: Text Processing :: Markup :: HTML', - 'Topic :: Text Processing :: Markup :: LaTeX', - 'Topic :: Utilities', - ], - platforms='any', - packages=find_packages(exclude=['tests', 'utils']), - package_data = { - 'sphinx': ['py.typed'], - }, - include_package_data=True, - entry_points={ - 'console_scripts': [ - 'sphinx-build = sphinx.cmd.build:main', - 'sphinx-quickstart = sphinx.cmd.quickstart:main', - 'sphinx-apidoc = sphinx.ext.apidoc:main', - 'sphinx-autogen = sphinx.ext.autosummary.generate:main', - ], - 'distutils.commands': [ - 'build_sphinx = sphinx.setup_command:BuildDoc', - ], - }, - python_requires=">=3.6", - install_requires=install_requires, - extras_require=extras_require, -) diff --git a/sphinx/__init__.py b/sphinx/__init__.py index f1377c5d5ea..9cdb8f74252 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -1,13 +1,11 @@ """The Sphinx documentation toolchain.""" # Keep this file executable as-is in Python 3! -# (Otherwise getting the version out of it from setup.py is impossible.) +# (Otherwise getting the version out of it when packaging is impossible.) import os -import subprocess import warnings from os import path -from subprocess import PIPE from .deprecation import RemovedInNextVersionWarning @@ -21,8 +19,8 @@ warnings.filterwarnings('ignore', 'The frontend.Option class .*', DeprecationWarning, module='docutils.frontend') -__version__ = '5.1.1' -__released__ = '5.1.1' # used when Sphinx builds its own docs +__version__ = '5.2.1' +__display_version__ = __version__ # used for command line version #: Version info for better programmatic use. #: @@ -32,22 +30,26 @@ #: #: .. versionadded:: 1.2 #: Before version 1.2, check the string ``sphinx.__version__``. -version_info = (5, 1, 1, 'final', 0) +version_info = (5, 2, 1, 'final', 0) package_dir = path.abspath(path.dirname(__file__)) -__display_version__ = __version__ # used for command line version -if __version__.endswith('+'): - # try to find out the commit hash if checked out from git, and append - # it to __version__ (since we use this value from setup.py, it gets - # automatically propagated to an installed copy as well) - __display_version__ = __version__ - __version__ = __version__[:-1] # remove '+' for PEP-440 version spec. +_in_development = False +if _in_development: + # Only import subprocess if needed + import subprocess + try: - ret = subprocess.run(['git', 'show', '-s', '--pretty=format:%h'], - cwd=package_dir, - stdout=PIPE, stderr=PIPE, encoding='ascii') - if ret.stdout: - __display_version__ += '/' + ret.stdout.strip() - except Exception: - pass + ret = subprocess.run( + ['git', 'show', '-s', '--pretty=format:%h'], + cwd=package_dir, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + encoding='ascii', + ).stdout + if ret: + __display_version__ += '+/' + ret.strip() + del ret + finally: + del subprocess +del _in_development diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 0a4a079daf5..e22ce5fa20e 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -1,6 +1,6 @@ -"""Additional docutils nodes.""" +"""Document tree nodes that Sphinx defines on top of those in Docutils.""" -from typing import TYPE_CHECKING, Any, Dict, List, Sequence +from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence import docutils from docutils import nodes @@ -27,7 +27,7 @@ class document(nodes.document): in your extensions. It will be removed without deprecation period. """ - def set_id(self, node: Element, msgnode: Element = None, + def set_id(self, node: Element, msgnode: Optional[Element] = None, suggested_prefix: str = '') -> str: if docutils.__version_info__ >= (0, 16): ret = super().set_id(node, msgnode, suggested_prefix) # type: ignore @@ -119,7 +119,7 @@ def extract_original_messages(self) -> List[str]: ############################################################# class _desc_classes_injector(nodes.Element, not_smartquotable): - """Helper base class for injecting a fixes list of classes. + """Helper base class for injecting a fixed list of classes. Use as the first base class. """ @@ -390,7 +390,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement): class centered(nodes.Part, nodes.TextElement): - """Deprecated.""" + """This node is deprecated.""" class acks(nodes.Element): @@ -455,13 +455,18 @@ class pending_xref(nodes.Inline, nodes.Element): class pending_xref_condition(nodes.Inline, nodes.TextElement): - """Node for cross-references that are used to choose appropriate - content of the reference by conditions on the resolving phase. + """Node representing a potential way to create a cross-reference and the + condition in which this way should be used. - When the :py:class:`pending_xref` node contains one or more - **pending_xref_condition** nodes, the cross-reference resolver - should choose the content of the reference using defined conditions - in ``condition`` attribute of each pending_xref_condition nodes:: + This node is only allowed to be placed under a :py:class:`pending_xref` + node. A **pending_xref** node must contain either no **pending_xref_condition** + nodes or it must only contains **pending_xref_condition** nodes. + + The cross-reference resolver will replace a :py:class:`pending_xref` which + contains **pending_xref_condition** nodes by the content of exactly one of + those **pending_xref_condition** nodes' content. It uses the **condition** + attribute to decide which **pending_xref_condition** node's content to + use. For example, let us consider how the cross-reference resolver acts on:: @@ -471,32 +476,26 @@ class pending_xref_condition(nodes.Inline, nodes.TextElement): io.StringIO - After the processing of cross-reference resolver, one of the content node - under pending_xref_condition node is chosen by its condition and to be - removed all of pending_xref_condition nodes:: + If the cross-reference resolver successfully resolves the cross-reference, + then it rewrites the **pending_xref** as:: - # When resolved the cross-reference successfully StringIO - # When resolution is failed + Otherwise, if the cross-reference resolution failed, it rewrites the + **pending_xref** as:: + io.StringIO - .. note:: This node is only allowed to be placed under pending_xref node. - It is not allows to place it under other nodes. In addition, - pending_xref node must contain only pending_xref_condition - nodes if it contains one or more pending_xref_condition nodes. - - The pending_xref_condition node should have **condition** attribute. + The **pending_xref_condition** node should have **condition** attribute. Domains can be store their individual conditions into the attribute to filter contents on resolving phase. As a reserved condition name, ``condition="*"`` is used for the fallback of resolution failure. Additionally, as a recommended condition name, ``condition="resolved"`` - is used for the representation of resolstion success in the intersphinx - module. + represents a resolution success in the intersphinx module. .. versionadded:: 4.0 """ diff --git a/sphinx/application.py b/sphinx/application.py index e0e77a3f5e6..10c03a268f0 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -128,9 +128,10 @@ class Sphinx: _warncount: int def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir: str, - buildername: str, confoverrides: Dict = None, + buildername: str, confoverrides: Optional[Dict] = None, status: Optional[IO] = sys.stdout, warning: Optional[IO] = sys.stderr, - freshenv: bool = False, warningiserror: bool = False, tags: List[str] = None, + freshenv: bool = False, warningiserror: bool = False, + tags: Optional[List[str]] = None, verbosity: int = 0, parallel: int = 0, keep_going: bool = False, pdb: bool = False) -> None: self.phase = BuildPhase.INITIALIZATION @@ -335,7 +336,7 @@ def _init_builder(self) -> None: # ---- main "build" method ------------------------------------------------- - def build(self, force_all: bool = False, filenames: List[str] = None) -> None: + def build(self, force_all: bool = False, filenames: Optional[List[str]] = None) -> None: self.phase = BuildPhase.READING try: if force_all: @@ -605,7 +606,7 @@ def depart_math_html(self, node): self.registry.add_translation_handlers(node, **kwargs) def add_enumerable_node(self, node: Type[Element], figtype: str, - title_getter: TitleGetter = None, override: bool = False, + title_getter: Optional[TitleGetter] = None, override: bool = False, **kwargs: Tuple[Callable, Callable]) -> None: """Register a Docutils node class as a numfig target. @@ -638,8 +639,9 @@ def add_directive(self, name: str, cls: Type[Directive], override: bool = False) :param name: The name of the directive :param cls: A directive class - :param override: If true, install the directive forcedly even if another directive + :param override: If false, do not install it if another directive is already installed as the same name + If true, unconditionally install the directive. For example, a custom directive named ``my-directive`` would be added like this: @@ -686,8 +688,9 @@ def add_role(self, name: str, role: Any, override: bool = False) -> None: :param name: The name of role :param role: A role function - :param override: If true, install the role forcedly even if another role is already - installed as the same name + :param override: If false, do not install it if another role + is already installed as the same name + If true, unconditionally install the role. For more details about role functions, see `the Docutils docs `__ . @@ -707,8 +710,9 @@ def add_generic_role(self, name: str, nodeclass: Any, override: bool = False) -> Register a Docutils role that does nothing but wrap its contents in the node given by *nodeclass*. - If *override* is True, the given *nodeclass* is forcedly installed even if - a role named as *name* is already installed. + :param override: If false, do not install it if another role + is already installed as the same name + If true, unconditionally install the role. .. versionadded:: 0.6 .. versionchanged:: 1.8 @@ -727,8 +731,9 @@ def add_domain(self, domain: Type[Domain], override: bool = False) -> None: """Register a domain. :param domain: A domain class - :param override: If true, install the domain forcedly even if another domain + :param override: If false, do not install it if another domain is already installed as the same name + If true, unconditionally install the domain. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -746,8 +751,9 @@ def add_directive_to_domain(self, domain: str, name: str, :param domain: The name of target domain :param name: A name of directive :param cls: A directive class - :param override: If true, install the directive forcedly even if another directive + :param override: If false, do not install it if another directive is already installed as the same name + If true, unconditionally install the directive. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -765,8 +771,9 @@ def add_role_to_domain(self, domain: str, name: str, role: Union[RoleFunction, X :param domain: The name of the target domain :param name: The name of the role :param role: The role function - :param override: If true, install the role forcedly even if another role is already - installed as the same name + :param override: If false, do not install it if another role + is already installed as the same name + If true, unconditionally install the role. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -782,8 +789,9 @@ def add_index_to_domain(self, domain: str, index: Type[Index], override: bool = :param domain: The name of the target domain :param index: The index class - :param override: If true, install the index forcedly even if another index is - already installed as the same name + :param override: If false, do not install it if another index + is already installed as the same name + If true, unconditionally install the index. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -792,7 +800,8 @@ def add_index_to_domain(self, domain: str, index: Type[Index], override: bool = self.registry.add_index_to_domain(domain, index) def add_object_type(self, directivename: str, rolename: str, indextemplate: str = '', - parse_node: Callable = None, ref_nodeclass: Type[TextElement] = None, + parse_node: Optional[Callable] = None, + ref_nodeclass: Optional[Type[TextElement]] = None, objname: str = '', doc_field_types: List = [], override: bool = False ) -> None: """Register a new object type. @@ -859,7 +868,7 @@ def add_object_type(self, directivename: str, rolename: str, indextemplate: str override=override) def add_crossref_type(self, directivename: str, rolename: str, indextemplate: str = '', - ref_nodeclass: Type[TextElement] = None, objname: str = '', + ref_nodeclass: Optional[Type[TextElement]] = None, objname: str = '', override: bool = False) -> None: """Register a new crossref object type. @@ -887,8 +896,10 @@ def add_crossref_type(self, directivename: str, rolename: str, indextemplate: st (Of course, the element following the ``topic`` directive needn't be a section.) - If *override* is True, the given crossref_type is forcedly installed even if - a crossref_type having the same name is already installed. + + :param override: If false, do not install it if another cross-reference type + is already installed as the same name + If true, unconditionally install the cross-reference type. .. versionchanged:: 1.8 Add *override* keyword. @@ -947,20 +958,22 @@ def add_js_file(self, filename: Optional[str], priority: int = 500, loading_method: Optional[str] = None, **kwargs: Any) -> None: """Register a JavaScript file to include in the HTML output. - :param filename: The filename of the JavaScript file. It must be relative to the HTML - static path, a full URI with scheme, or ``None`` value. The ``None`` - value is used to create inline ``