IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Enable 'nit-picky mode' for Sphinx's documentation

Browse Source 
Fix several reference errors throughout the documentation and set
``nitpick_ignore`` in ``doc/conf.py``.
This commit is contained in:
Adam Turner
2023-04-06 23:11:39 +01:00
parent b2349254fc
commit 7ecf037280
31 changed files with 206 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/workflows/builddoc.yml vendored
View File

@@ -33,4 +33,5 @@ jobs:
-m sphinx
-M html ./doc ./build/sphinx
-W
-n
--keep-going

98
CHANGES
View File

@@ -489,7 +489,7 @@ Bugs fixed
* #10498: gettext: TypeError is raised when sorting warning messages if a node
has no line number. Patch by Adam Turner.
* #10493: HTML Theme: :rst:dir:`topic` directive is rendered incorrectly with
* #10493: HTML Theme: :dudir:`topic` directive is rendered incorrectly with
Docutils 0.18. Patch by Adam Turner.
* #10495: IndexError is raised for a :rst:role:`kbd` role having a separator.
Patch by Adam Turner.
@@ -593,7 +593,7 @@ Features added
underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
EMCAScript 2018. Patch by Adam Turner.
* #10302: C++, add support for conditional expressions (``?:``).
* #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role`
* #5157, #10251: Inline code is able to be highlighted via :dudir:`role`
directive
* #10337: Make sphinx-build faster by caching Publisher object during build.
Patch by Adam Turner.
@@ -916,7 +916,7 @@ Bugs fixed
* #9697: py domain: An index entry with parens was registered for ``py:method``
directive with ``:property:`` option
* #9775: py domain: Literal typehint was converted to a cross reference when
:confval:`autodoc_typehints='description'`
:confval:`autodoc_typehints`\ ``='description'``
* #9708: needs_extension failed to check double-digit version correctly
* #9688: Fix Sphinx patched :dudir:`code` does not recognize ``:class:`` option
* #9733: Fix for logging handler flushing warnings in the middle of the docs
@@ -1209,7 +1209,8 @@ Incompatible changes
4.0.0b1
* #8539: autodoc: info-field-list is generated into the class description when
``autodoc_typehints='description'`` and ``autoclass_content='class'`` set
:confval:`autodoc_typehints`\ ``='description'`` and
:confval:`autoclass_content`\ ``='class'`` set
* #8898: extlinks: "%s" becomes required keyword in the link caption string
* domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate
methods that must be overridden in the concrete classes
@@ -1471,7 +1472,7 @@ Features added
functions in source code and keep them not evaluated for readability.
* #8619: html: kbd role generates customizable HTML tags for compound keys
* #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`
for :meth:`.Sphinx.add_js_file()` and :meth:`.Sphinx.add_css_file()`
* #6241: html: Allow to add JS/CSS files to the specific page when an extension
calls ``app.add_js_file()`` or ``app.add_css_file()`` on
:event:`html-page-context` event
@@ -1485,7 +1486,7 @@ Features added
* #8649: imgconverter: Skip availability check if builder supports the image
type
* #8573: napoleon: Allow to change the style of custom sections using
:confval:`napoleon_custom_styles`
:confval:`napoleon_custom_sections`
* #8004: napoleon: Type definitions in Google style docstrings are rendered as
references when :confval:`napoleon_preprocess_types` enabled
* #6241: mathjax: Include mathjax.js only on the document using equations
@@ -1672,7 +1673,7 @@ Features added
messages when failed to resolve a cross-reference
* #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference
* #6629: linkcheck: The builder now handles rate limits. See
:confval:`linkcheck_retry_on_rate_limit` for details.
:confval:`linkcheck_rate_limit_timeout` for details.
Bugs fixed
----------
@@ -1855,7 +1856,7 @@ Deprecated
* ``sphinx.ext.autodoc.merge_special_members_option()``
* ``sphinx.writers.texinfo.TexinfoWriter.desc``
* C, parsing of pre-v3 style type directives and roles, along with the options
:confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`.
:confval:`!c_allow_pre_v3` and :confval:`!c_warn_on_allowed_pre_v3`.
Features added
--------------
@@ -1874,7 +1875,7 @@ Features added
* #7690: napoleon: parse type strings and make them hyperlinks as possible. The
conversion rule can be updated via :confval:`napoleon_type_aliases`
* #8049: napoleon: Create a hyperlink for each the type of parameter when
:confval:`napoleon_use_params` is False
:confval:`napoleon_use_param` is False
* C, added :rst:dir:`c:alias` directive for inserting copies
of existing declarations.
* #7745: html: inventory is broken if the docname contains a space
@@ -1892,9 +1893,9 @@ Features added
and the ``:noindex:`` option.
* #7899: C, add possibility of parsing of some pre-v3 style type directives and
roles and try to convert them to equivalent v3 directives/roles.
Set the new option :confval:`c_allow_pre_v3` to ``True`` to enable this.
Set the new option :confval:`!c_allow_pre_v3` to ``True`` to enable this.
The warnings printed from this functionality can be suppressed by setting
:confval:`c_warn_on_allowed_pre_v3`` to ``True``.
:confval:`!c_warn_on_allowed_pre_v3` to ``True``.
The functionality is immediately deprecated.
* #7999: C, add support for named variadic macro arguments.
* #8071: Allow to suppress "self referenced toctrees" warning
@@ -1925,7 +1926,7 @@ Bugs fixed
* #4258: napoleon: decorated special methods are not shown
* #7799: napoleon: parameters are not escaped for combined params in numpydoc
* #7780: napoleon: multiple parameters declaration in numpydoc was wrongly
recognized when napoleon_use_params=True
recognized when ``napoleon_use_param=True``
* #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links
* #7846: html theme: XML-invalid files were generated
* #7894: gettext: Wrong source info is shown when using rst_epilog
@@ -2093,8 +2094,8 @@ Features added
* C++, parse parameterized noexcept specifiers.
* #7294: C++, parse expressions with user-defined literals.
* C++, parse trailing return types.
* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class:`,
:rst:dir:`py:exception:` and :rst:dir:`py:method:` directives
* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class`,
:rst:dir:`py:exception` and :rst:dir:`py:method` directives
* #7596: py domain: Change a type annotation for variables to a hyperlink
* #7770: std domain: :rst:dir:`option` directive support arguments in the form
of ``foo[=bar]``
@@ -2118,7 +2119,7 @@ Bugs fixed
* #7559: autodoc: misdetects a sync function is async
* #6857: autodoc: failed to detect a classmethod on Enum class
* #7562: autodoc: a typehint contains spaces is wrongly rendered under
autodoc_typehints='description' mode
:confval:`autodoc_typehints`\ ``='description'`` mode
* #7551: autodoc: failed to import nested class
* #7362: autodoc: does not render correct signatures for built-in functions
* #7654: autodoc: ``Optional[Union[foo, bar]]`` is presented as
@@ -2221,7 +2222,7 @@ Release 3.0.1 (released Apr 11, 2020)
Incompatible changes
--------------------
* #7418: std domain: :rst:dir:`term` role becomes case sensitive
* #7418: std domain: :rst:role:`term` role becomes case sensitive
Bugs fixed
----------
@@ -2232,8 +2233,8 @@ Bugs fixed
* #7418: std domain: duplication warning for glossary terms is case insensitive
* #7438: C++, fix merging overloaded functions in parallel builds.
* #7422: autodoc: fails with ValueError when using autodoc_mock_imports
* #7435: autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints
in signature for classes/methods
* #7435: autodoc: :confval:`autodoc_typehints`\ ``='description'`` doesn't
suppress typehints in signature for classes/methods
* #7451: autodoc: fails with AttributeError when an object returns non-string
object as a ``__doc__`` member
* #7423: crashed when giving a non-string object to logger
@@ -2644,7 +2645,7 @@ Features added
authentication information when doing ``linkcheck`` builds
* #6872: linkcheck: Handles HTTP 308 Permanent Redirect
* #6613: html: Wrap section number in span tag
* #6781: gettext: Add :confval:`gettext_last_translator' and
* #6781: gettext: Add :confval:`gettext_last_translator` and
:confval:`gettext_language_team` to customize headers of POT file
Bugs fixed
@@ -2783,7 +2784,7 @@ Bugs fixed
since Sphinx 1.8.0 (refs: #6533)
* #6531: Failed to load last environment object when extension added
* #736: Invalid sort in pair index
* #6527: :confval:`last_updated` wrongly assumes timezone as UTC
* #6527: :data:`last_updated` wrongly assumes timezone as UTC
* #5592: std domain: :rst:dir:`option` directive registers an index entry for
each comma separated option
* #6549: sphinx-build: Escaped characters in error messages
@@ -2898,7 +2899,7 @@ Features added
- ``PythonDomain.note_object()``
- ``SphinxDirective.set_source_info()``
* #6180: Support ``--keep-going`` with BuildDoc setup command
* #6180: Support ``--keep-going`` with ``BuildDoc`` setup command
* ``math`` directive now supports ``:class:`` option
* todo: ``todo`` directive now supports ``:name:`` option
* Enable override via environment of ``SPHINXOPTS`` and ``SPHINXBUILD`` Makefile
@@ -2928,7 +2929,7 @@ Features added
- ``:property:``
- ``:staticmethod:``
* rst domain: Add :rst:dir:`directive:option` directive to describe the option
* rst domain: Add :rst:dir:`rst:directive:option` directive to describe the option
for directive
* #6306: html: Add a label to search form for accessability purposes
* #4390: html: Consistent and semantic CSS for signatures
@@ -2975,9 +2976,9 @@ Bugs fixed
* RemovedInSphinx30Warning is marked as pending
* deprecation warnings are not emitted
- sphinx.application.CONFIG_FILENAME
- sphinx.builders.htmlhelp
- :confval:`viewcode_import`
- ``sphinx.application.CONFIG_FILENAME``
- ``sphinx.builders.htmlhelp``
- :confval:`!viewcode_import`
* #6208: C++, properly parse full xrefs that happen to have a short xref as
prefix
@@ -3460,7 +3461,7 @@ Incompatible changes
1.8.0b1
* #5156: the :py:mod:`sphinx.ext.graphviz: extension runs `dot` in the
* #5156: the :py:mod:`sphinx.ext.graphviz` extension runs ``dot`` in the
directory of the document being built instead of in the root directory of
the documentation.
* #4460: extensions which stores any data to environment should return the
@@ -3485,7 +3486,7 @@ Incompatible changes
* #4811: The files under :confval:`html_static_path` are excluded from source
files.
* latex: Use ``\sphinxcite`` for citation references instead ``\hyperref``
* The config value ``viewcode_import`` is renamed to
* The config value :confval:`!viewcode_import` is renamed to
:confval:`viewcode_follow_imported_members` (refs: #4035)
* #1857: latex: :confval:`latex_show_pagerefs` does not add pagerefs for
citations
@@ -3526,7 +3527,7 @@ Deprecated
* :confval:`autodoc_default_flags` is deprecated
* quickstart: ``--epub`` option becomes default, so it is deprecated
* Drop function based directive support. For now, Sphinx only supports class
based directives (see :class:`~Directive`)
based directives (see :class:`~docutils.parsers.rst.Directive`)
* ``sphinx.util.docutils.directive_helper()`` is deprecated
* ``sphinx.cmdline`` is deprecated
* ``sphinx.make_mode`` is deprecated
@@ -4102,8 +4103,8 @@ Features removed
* Configuration variables
- html_use_smartypants
- latex_keep_old_macro_names
- :confval:`!html_use_smartypants`
- :confval:`!latex_keep_old_macro_names`
- latex_elements['footer']
* utility methods of ``sphinx.application.Sphinx`` class
@@ -4429,7 +4430,7 @@ Incompatible changes
option and other options (refs: #3416)
* LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine
= 'lualatex'`` be used only on up-to-date TeX installs (refs #3070, #3466)
* :confval:`latex_keep_old_macro_names` default value has been changed from
* :confval:`!latex_keep_old_macro_names` default value has been changed from
``True`` to ``False``. This means that some LaTeX macros for styling are
by default defined only with ``\sphinx..`` prefixed names. (refs: #3429)
* Footer "Continued on next page" of LaTeX longtable's now not framed (refs:
@@ -4635,8 +4636,8 @@ Deprecated
* latex package ``footnote`` is not loaded anymore by its bundled replacement
``footnotehyper-sphinx``. The redefined macros keep the same names as in the
original package.
* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be
removed at 1.7, and already its default value has changed from ``True`` to
* #3429: deprecate config setting :confval:`!latex_keep_old_macro_names`. It will
be removed at 1.7, and already its default value has changed from ``True`` to
``False``.
* #3221: epub2 builder is deprecated
* #3254: ``sphinx.websupport`` is now separated into independent package;
@@ -4902,7 +4903,7 @@ Incompatible changes
* Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even
if ``epub_use_index = False``.
* ``html_translator_class`` is now deprecated.
Use `Sphinx.set_translator()` API instead.
Use :meth:`~sphinx.application.Sphinx.set_translator` API instead.
* Drop python 2.6 and 3.3 support
* Drop epub3 builder's ``epub3_page_progression_direction`` option (use
``epub3_writing_mode``).
@@ -5261,7 +5262,7 @@ Incompatible changes
Features added
--------------
* new config option ``latex_keep_old_macro_names``, defaults to True. If False,
* new config option :confval:`!latex_keep_old_macro_names`, defaults to True. If False,
lets macros (for text styling) be defined only with ``\sphinx``-prefixed names
* latex writer allows user customization of "shadowed" boxes (topics), via
three length variables.
@@ -6649,7 +6650,8 @@ Features added
* Other builders:
- Added the Docutils-native XML and pseudo-XML builders. See
:class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
:class:`~sphinx.builders.xml.XMLBuilder` and
:class:`~sphinx.builders.xml.PseudoXMLBuilder`.
- PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
- PR#123, #1106: Add `epub_use_index` configuration value. If
provided, it will be used instead of `html_use_index` for epub
@@ -6916,26 +6918,26 @@ Features added
* Other builders:
- #516: Added new value of the `latex_show_urls` option to
- #516: Added new value of the :confval:`latex_show_urls` option to
show the URLs in footnotes.
- #209: Added `text_newlines` and `text_sectionchars`
- #209: Added :confval:`text_newlines` and :confval:`text_sectionchars`
config values.
- Added `man_show_urls` config value.
- Added :confval:`man_show_urls` config value.
- #472: linkcheck builder: Check links in parallel, use HTTP HEAD
requests and allow configuring the timeout. New config values:
`linkcheck_timeout` and `linkcheck_workers`.
- #521: Added `linkcheck_ignore` config value.
:confval:`linkcheck_timeout` and :confval:`linkcheck_workers`.
- #521: Added :confval:`linkcheck_ignore` config value.
- #28: Support row/colspans in tables in the LaTeX builder.
* Configuration and extensibility:
- #537: Added `nitpick_ignore`.
- #537: Added :confval:`nitpick_ignore`.
- #306: Added :event:`env-get-outdated` event.
- :meth:`.Application.add_stylesheet` now accepts full URIs.
- :meth:`!Application.add_stylesheet` now accepts full URIs.
* Autodoc:
- #564: Add `autodoc_docstring_signature`. When enabled (the
- #564: Add :confval:`autodoc_docstring_signature`. When enabled (the
default), autodoc retrieves the signature from the first line of the
docstring, if it is found there.
- #176: Provide ``private-members`` option for autodoc directives.
@@ -7195,7 +7197,7 @@ Release 1.0.2 (Aug 14, 2010)
============================
* #490: Fix cross-references to objects of types added by the
:func:`~.Sphinx.add_object_type` API function.
:func:`~sphinx.application.Sphinx.add_object_type` API function.
* Fix handling of doc field types for different directive types.
@@ -7267,7 +7269,7 @@ Incompatible changes
* The old markup for defining and linking to C directives is now
deprecated. It will not work anymore in future versions without
activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx
activating the ``oldcmarkup`` extension; in Sphinx
1.0, it is activated by default.
* Removed support for old dependency versions; requirements are now:
@@ -7376,7 +7378,7 @@ Features added
- Added `needs_sphinx` config value and
:meth:`~sphinx.application.Sphinx.require_sphinx` application API
method.
- #200: Added :meth:`~sphinx.application.Sphinx.add_stylesheet`
- #200: Added :meth:`!add_stylesheet`
application API method.
* Extensions:
@@ -8030,7 +8032,7 @@ New features added
- Highlighted code blocks now have CSS classes that make it possible
to style them depending on their language.
- HTML ``<meta>`` tags via the docutils ``meta`` directive are now
- HTML ``<meta>`` tags via the docutils :dudir:`meta` directive are now
supported.
- ``SerializingHTMLBuilder`` was added as new abstract builder that

57
doc/conf.py
View File

@@ -121,6 +121,63 @@ intersphinx_mapping = {
locale_dirs = ['locale/']
gettext_compact = False
nitpick_ignore = {
('cpp:class', 'template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner'), # NoQA: E501
('cpp:identifier', 'MyContainer'),
('js:func', 'SomeError'),
('js:func', 'number'),
('js:func', 'string'),
('py:attr', 'srcline'),
('py:class', 'Element'), # sphinx.domains.Domain
('py:class', 'Node'), # sphinx.domains.Domain
('py:class', 'RoleFunction'), # sphinx.domains.Domain
('py:class', 'Theme'), # sphinx.application.TemplateBridge
('py:class', 'TitleGetter'), # sphinx.domains.Domain
('py:class', 'XRefRole'), # sphinx.domains.Domain
('py:class', 'docutils.nodes.Element'),
('py:class', 'docutils.nodes.Node'),
('py:class', 'docutils.nodes.NodeVisitor'),
('py:class', 'docutils.nodes.TextElement'),
('py:class', 'docutils.nodes.document'),
('py:class', 'docutils.nodes.system_message'),
('py:class', 'docutils.parsers.Parser'),
('py:class', 'docutils.parsers.rst.states.Inliner'),
('py:class', 'docutils.transforms.Transform'),
('py:class', 'nodes.NodeVisitor'),
('py:class', 'nodes.document'),
('py:class', 'nodes.reference'),
('py:class', 'pygments.lexer.Lexer'),
('py:class', 'sphinx.directives.ObjDescT'),
('py:class', 'sphinx.domains.IndexEntry'),
('py:class', 'sphinx.ext.autodoc.Documenter'),
('py:class', 'sphinx.errors.NoUri'),
('py:class', 'sphinx.roles.XRefRole'),
('py:class', 'sphinx.search.SearchLanguage'),
('py:class', 'sphinx.theming.Theme'),
('py:class', 'sphinxcontrib.websupport.errors.DocumentNotFoundError'),
('py:class', 'sphinxcontrib.websupport.errors.UserNotAuthorizedError'),
('py:exc', 'docutils.nodes.SkipNode'),
('py:exc', 'sphinx.environment.NoUri'),
('py:func', 'setup'),
('py:func', 'sphinx.util.nodes.nested_parse_with_titles'),
# Error in sphinxcontrib.websupport.core::WebSupport.add_comment
('py:meth', 'get_comments'),
('py:mod', 'autodoc'),
('py:mod', 'docutils.nodes'),
('py:mod', 'docutils.parsers.rst.directives'),
('py:mod', 'sphinx.ext'),
('py:obj', 'sphinx.util.relative_uri'),
('rst:role', 'c:any'),
('std:confval', 'autodoc_inherit_docstring'),
('std:confval', 'automodule_skip_lines'),
('std:confval', 'autossummary_imported_members'),
('std:confval', 'gettext_language_team'),
('std:confval', 'gettext_last_translator'),
('std:confval', 'globaltoc_collapse'),
('std:confval', 'globaltoc_includehidden'),
('std:confval', 'globaltoc_maxdepth'),
}
# -- Extension interface -------------------------------------------------------

2
doc/development/overview.rst
View File

@@ -15,7 +15,7 @@ extension developer.
:noindex:
To ensure that another extension is activated as a part of your own extension,
use the :meth:`Sphinx.setup_extension` method. This will
use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will
activate another extension at run-time, ensuring that you have access to its
functionality.

6
doc/development/templating.rst
View File

@@ -26,9 +26,9 @@ No. You have several other options:
:class:`~sphinx.builders.html.StandaloneHTMLBuilder` and calls your template
engine of choice.
* You can use the :class:`~sphinx.builders.html.PickleHTMLBuilder` that produces
pickle files with the page contents, and postprocess them using a custom tool,
or use them in your Web application.
* You can use the :class:`~sphinxcontrib.serializinghtml.PickleHTMLBuilder` that
produces pickle files with the page contents, and postprocess them using a
custom tool, or use them in your Web application.
Jinja/Sphinx Templating Primer

6
doc/development/theming.rst
View File

@@ -36,7 +36,7 @@ theme name), containing the following:
output static directory on build. These can be images, styles, script files.
The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
Python :mod:`ConfigParser` module) and has the following structure:
Python :mod:`configparser` module) and has the following structure:
.. sourcecode:: ini
@@ -69,7 +69,7 @@ Python :mod:`ConfigParser` module) and has the following structure:
* The **pygments_dark_style** setting gives the name of a Pygments style to use
for highlighting when the CSS media query ``(prefers-color-scheme: dark)``
evaluates to true. It is injected into the page using
:meth:`~Sphinx.add_css_file()`.
:meth:`~sphinx.application.Sphinx.add_css_file()`.
* The **sidebars** setting gives the comma separated list of sidebar templates
for constructing sidebars. This can be overridden by the user in the
@@ -306,7 +306,7 @@ Will result in the following static file placed in your HTML's build output:
See :ref:`theming-static-templates` for more information.
Second, you may use the :meth:`Sphinx.add_js_file` method without pointing it
Second, you may use the :meth:`.Sphinx.add_js_file` method without pointing it
to a file. Normally, this method is used to insert a new JavaScript file
into your site. However, if you do *not* pass a file path, but instead pass
a string to the "body" argument, then this text will be inserted as JavaScript

7
doc/development/tutorials/autodoc_ext.rst
View File

@@ -54,9 +54,10 @@ Start with ``setup`` function for the extension.
:pyobject: setup
The :meth:`~Sphinx.setup_extension` method will pull the autodoc extension
because our new extension depends on autodoc. :meth:`~Sphinx.add_autodocumenter`
is the method that registers our new auto documenter class.
The :meth:`~sphinx.application.Sphinx.setup_extension` method will pull the
autodoc extension because our new extension depends on autodoc.
:meth:`~sphinx.application.Sphinx.add_autodocumenter` is the method that
registers our new auto documenter class.
We want to import certain objects from the autodoc extension:

2
doc/development/tutorials/todo.rst
View File

@@ -112,7 +112,7 @@ is just a "general" node.
It is important to know that while you can extend Sphinx without
leaving your ``conf.py``, if you declare an inherited node right
there, you'll hit an unobvious :py:class:`PickleError`. So if
there, you'll hit an unobvious :py:class:`~pickle.PickleError`. So if
something goes wrong, please make sure that you put inherited nodes
into a separate Python module.

16
doc/extdev/appapi.rst
View File

@@ -278,16 +278,16 @@ Here is a more detailed list of these events.
Emitted when a cross-reference to an object cannot be resolved.
If the event handler can resolve the reference, it should return a
new docutils node to be inserted in the document tree in place of the node
*node*. Usually this node is a :class:`reference` node containing *contnode*
as a child.
*node*. Usually this node is a :class:`~nodes.reference` node containing
*contnode* as a child.
If the handler can not resolve the cross-reference,
it can either return ``None`` to let other handlers try,
or raise :class:`NoUri` to prevent other handlers in trying and suppress
a warning about this cross-reference being unresolved.
or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in
trying and suppress a warning about this cross-reference being unresolved.
:param env: The build environment (``app.builder.env``).
:param node: The :class:`pending_xref` node to be resolved. Its attributes
``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
:param node: The :class:`~sphinx.addnodes.pending_xref` node to be resolved.
Its ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
determine the type and target of the reference.
:param contnode: The node that carries the text and formatting inside the
future reference and should be a child of the returned reference node.
@@ -330,8 +330,8 @@ Here is a more detailed list of these events.
.. event:: env-updated (app, env)
Emitted when the :meth:`update` method of the build environment has
completed, that is, the environment and all doctrees are now up-to-date.
Emitted after reading all documents, when the environment and all
doctrees are now up-to-date.
You can return an iterable of docnames from the handler. These documents
will then be considered updated, and will be (re-)written during the writing

10
doc/extdev/deprecated.rst
View File

@@ -1355,17 +1355,17 @@ The following is a list of deprecated interfaces.
- 4.0
- N/A
* - :rst:dir:`highlightlang`
* - :rst:dir:`!highlightlang`
- 1.8
- 4.0
- :rst:dir:`highlight`
* - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
* - :meth:`!add_stylesheet`
- 1.8
- 6.0
- :meth:`~sphinx.application.Sphinx.add_css_file()`
* - :meth:`~sphinx.application.Sphinx.add_javascript()`
* - :meth:`!add_javascript()`
- 1.8
- 4.0
- :meth:`~sphinx.application.Sphinx.add_js_file()`
@@ -1467,7 +1467,7 @@ The following is a list of deprecated interfaces.
- 3.0
- ``sphinx.builders.latex.nodes.math_reference``
* - ``viewcode_import`` (config value)
* - :confval:`!viewcode_import` (config value)
- 1.8
- 3.0
- :confval:`viewcode_follow_imported_members`
@@ -1825,7 +1825,7 @@ The following is a list of deprecated interfaces.
* - ``StandaloneHTMLBuilder.css_files``
- 1.6
- 2.0
- :meth:`~sphinx.application.Sphinx.add_stylesheet()`
- :meth:`!add_stylesheet`
* - ``document.settings.gettext_compact``
- 1.8

2
doc/extdev/markupapi.rst
View File

@@ -63,7 +63,7 @@ using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`.
.. attribute:: content
The directive content, if given, as a :class:`.ViewList`.
The directive content, if given, as a :class:`!ViewList`.
.. attribute:: lineno

4
doc/glossary.rst
View File

@@ -81,8 +81,8 @@ Glossary
object
The basic building block of Sphinx documentation. Every "object
directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a
block; and most objects can be cross-referenced to.
directive" (e.g. :rst:dir:`py:function` or :rst:dir:`object`) creates such
a block; and most objects can be cross-referenced to.
RemoveInSphinxXXXWarning
The feature which is warned will be removed in Sphinx-XXX version.

2
doc/latex.rst
View File

@@ -83,7 +83,7 @@ The ``latex_elements`` configuration setting
A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
into the generated ``.tex`` files. Its ``'sphinxsetup'`` key is described
:ref:`separately <latexsphinxsetup>`. It allows also local configurations
inserted in generated files, via :rst:dir:`raw` directives. For example, in
inserted in generated files, via :dudir:`raw` directives. For example, in
the PDF documentation this chapter is styled especially, as will be described
later.

4
doc/man/sphinx-apidoc.rst
View File

@@ -11,8 +11,8 @@ Description
-----------
:program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources
that, using the :rst:dir:`autodoc` extension, document a whole package in the
style of other automatic API documentation tools.
that, using the :py:mod:`~sphinx.ext.autodoc` extension, document a whole
package in the style of other automatic API documentation tools.
*MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s

8
doc/man/sphinx-autogen.rst
View File

@@ -10,8 +10,8 @@ Description
-----------
:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
that, using the :rst:dir:`autodoc` extension, document items included in
:rst:dir:`autosummary` listing(s).
that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included
in :rst:dir:`autosummary` listing(s).
*sourcefile* is the path to one or more reStructuredText documents containing
:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
@@ -88,8 +88,8 @@ then the following stub files will be created in ``docs``::
├── foobar.bar.baz.rst
└── foobar.foo.rst
and each of those files will contain a :rst:dir:`autodoc` directive and some
other information.
and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive
and some other information.
See also
--------

2
doc/man/sphinx-quickstart.rst
View File

@@ -78,7 +78,7 @@ Options
.. option:: --ext-autodoc
Enable `sphinx.ext.autodoc` extension.
Enable :py:mod:`sphinx.ext.autodoc` extension.
.. option:: --ext-doctest

4
doc/usage/advanced/setuptools.rst
View File

@@ -4,11 +4,11 @@ Setuptools integration
======================
Sphinx supports integration with setuptools and distutils through a custom
command - :class:`~sphinx.setup_command.BuildDoc`.
command - :class:`!sphinx.setup_command.BuildDoc`.
.. deprecated:: 5.0
This feature will be removed in v7.0.
This feature will be removed in Sphinx 7.0.
Using setuptools integration
----------------------------

2
doc/usage/advanced/websupport/quickstart.rst
View File

@@ -252,4 +252,4 @@ class when instantiating your support object::
support = WebSupport(..., moderation_callback=moderation_callback)
The moderation callback must take one argument, which will be the same comment
dict that is returned by :meth:`add_comment`.
dict that is returned by :meth:`.WebSupport.add_comment`.

22
doc/usage/configuration.rst
View File

@@ -307,7 +307,7 @@ General configuration
"filter". The default is ``None``, which doesn't reassign the default role.
The default role can always be set within individual documents using the
standard reST :rst:dir:`default-role` directive.
standard reST :dudir:`default-role` directive.
.. versionadded:: 0.4
@@ -440,12 +440,14 @@ General configuration
.. confval:: nitpick_ignore
A list of ``(type, target)`` tuples (by default empty) that should be
A set or list of ``(type, target)`` tuples (by default empty) that should be
ignored when generating warnings in "nitpicky mode". Note that ``type``
should include the domain name if present. Example entries would be
``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``.
.. versionadded:: 1.1
.. versionchanged:: 6.2
Changed allowable container types to a set, list, or tuple
.. confval:: nitpick_ignore_regex
@@ -460,6 +462,8 @@ General configuration
``('py:class', 'food.bar.Barman')``.
.. versionadded:: 4.1
.. versionchanged:: 6.2
Changed allowable container types to a set, list, or tuple
.. confval:: numfig
@@ -1132,7 +1136,7 @@ that use Sphinx's HTMLWriter class.
As a special attribute, *priority* can be set as an integer to load the CSS
file earlier or lazier step. For more information, refer
:meth:`Sphinx.add_css_files()`.
:meth:`.Sphinx.add_css_file()`.
.. versionadded:: 1.8
.. versionchanged:: 3.5
@@ -1155,7 +1159,7 @@ that use Sphinx's HTMLWriter class.
As a special attribute, *priority* can be set as an integer to load the CSS
file earlier or lazier step. For more information, refer
:meth:`Sphinx.add_css_files()`.
:meth:`.Sphinx.add_css_file()`.
.. versionadded:: 1.8
.. versionchanged:: 3.5
@@ -1217,7 +1221,7 @@ that use Sphinx's HTMLWriter class.
.. confval:: html_last_updated_fmt
If this is not None, a 'Last updated on:' timestamp is inserted
at every page bottom, using the given :func:`strftime` format.
at every page bottom, using the given :func:`~time.strftime` format.
The empty string is equivalent to ``'%b %d, %Y'`` (or a
locale-dependent equivalent).
@@ -1480,8 +1484,8 @@ that use Sphinx's HTMLWriter class.
:type:
_`type` is dotted module path string to specify Splitter implementation
which should be derived from :class:`sphinx.search.ja.BaseSplitter`. If
not specified or None is specified,
which should be derived from :class:`!sphinx.search.ja.BaseSplitter`. If
not specified or ``None`` is specified,
``'sphinx.search.ja.DefaultSplitter'`` will be used.
You can choose from these modules:
@@ -1732,7 +1736,7 @@ HTML builder, so the HTML options also apply where appropriate.
Italian it
========= ====
Defaults to :confval:`language`, or if that is not set, to :confval:`en`.
Defaults to :confval:`language`, or if that is not set, to ``'en'``.
.. confval:: applehelp_locale
@@ -1740,7 +1744,7 @@ HTML builder, so the HTML options also apply where appropriate.
the name of the ``.lproj`` folder inside the Help Book’s ``Resources``, and
is passed to the help indexer.
Defaults to :confval:`language`, or if that is not set, to :confval:`en`.
Defaults to :confval:`language`, or if that is not set, to ``'en'``.
.. confval:: applehelp_title

5
doc/usage/extensions/inheritance.rst
View File

@@ -131,6 +131,11 @@ part (``sphinx``) from all names::
:top-classes: sphinx.util.docutils.SphinxDirective
:parts: -1
.. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram
:nocontentsentry:
:noindexentry:
The internal class that implements the ``inheritance-diagram`` directive.
Configuration

8
doc/usage/extensions/napoleon.rst
View File

@@ -398,7 +398,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
.. seealso::
:attr:`napoleon_use_admonition_for_examples`
:confval:`napoleon_use_admonition_for_examples`
.. confval:: napoleon_use_admonition_for_references
@@ -408,7 +408,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
.. seealso::
:attr:`napoleon_use_admonition_for_examples`
:confval:`napoleon_use_admonition_for_examples`
.. confval:: napoleon_use_ivar
@@ -471,14 +471,14 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
keywords.
*Defaults to True.*
This behaves similarly to :attr:`napoleon_use_param`. Note unlike docutils,
This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils,
``:keyword:`` and ``:param:`` will not be treated the same way - there will
be a separate "Keyword Arguments" section, rendered in the same fashion as
"Parameters" section (type links created if possible)
.. seealso::
:attr:`napoleon_use_param`
:confval:`napoleon_use_param`
.. confval:: napoleon_use_rtype

4
doc/usage/restructuredtext/basics.rst
View File

@@ -544,7 +544,7 @@ for details.
If you want to use some substitutions for all documents, put them into
:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file
and include it into all documents you want to use them in, using the
:rst:dir:`include` directive. (Be sure to give the include file a file name
:dudir:`include` directive. (Be sure to give the include file a file name
extension differing from that of other source files, to avoid Sphinx finding it
as a standalone document.)
@@ -574,7 +574,7 @@ You can indent text after a comment start to form multiline comments::
HTML Metadata
-------------
The :rst:dir:`meta` directive (:dudir:`ref <meta>`) allows specifying the HTML
The :dudir:`meta` directive allows specifying the HTML
`metadata element`_ of a Sphinx documentation page. For example, the
directive::

1
doc/usage/restructuredtext/directives.rst
View File

@@ -490,6 +490,7 @@ __ https://pygments.org/docs/lexers
.. versionadded:: 2.1
.. rst:directive:: .. code-block:: [language]
.. sourcecode:: [language]
Example::

2
doc/usage/restructuredtext/domains.rst
View File

@@ -585,7 +585,7 @@ This will render like this:
: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
:type priority: int or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters

16
sphinx/application.py
View File

@@ -875,7 +875,7 @@ class Sphinx:
override: bool = False) -> None:
"""Register a new crossref object type.
This method is very similar to :meth:`add_object_type` except that the
This method is very similar to :meth:`~Sphinx.add_object_type` except that the
directive it generates must be empty, and will produce no output.
That means that you can add semantic targets to your sources, and refer
@@ -914,9 +914,9 @@ class Sphinx:
def add_transform(self, transform: type[Transform]) -> None:
"""Register a Docutils transform to be applied after parsing.
Add the standard docutils :class:`Transform` subclass *transform* to
the list of transforms that are applied after Sphinx parses a reST
document.
Add the standard docutils :class:`~docutils.transforms.Transform`
subclass *transform* to the list of transforms that are applied after
Sphinx parses a reST document.
:param transform: A transform class
@@ -949,9 +949,9 @@ class Sphinx:
def add_post_transform(self, transform: type[Transform]) -> None:
"""Register a Docutils transform to be applied before writing.
Add the standard docutils :class:`Transform` subclass *transform* to
the list of transforms that are applied before Sphinx writes a
document.
Add the standard docutils :class:`~docutils.transforms.Transform`
subclass *transform* to the list of transforms that are applied before
Sphinx writes a document.
:param transform: A transform class
"""
@@ -1132,7 +1132,7 @@ class Sphinx:
extension. It must be a subclass of
:class:`sphinx.ext.autodoc.Documenter`. This allows auto-documenting
new types of objects. See the source of the autodoc module for
examples on how to subclass :class:`Documenter`.
examples on how to subclass :class:`~sphinx.ext.autodoc.Documenter`.
If *override* is True, the given *cls* is forcedly installed even if
a documenter having the same name is already installed.

5
sphinx/builders/__init__.py
View File

@@ -61,7 +61,7 @@ class Builder:
epilog = ''
#: default translator class for the builder. This can be overridden by
#: :py:meth:`app.set_translator()`.
#: :py:meth:`~sphinx.application.Sphinx.set_translator`.
default_translator_class: type[nodes.NodeVisitor] = None
# doctree versioning method
versioning_method = 'none'
@@ -317,7 +317,8 @@ class Builder:
) -> None:
"""Main build method.
First updates the environment, and then calls :meth:`write`.
First updates the environment, and then calls
:meth:`!write`.
"""
if summary:
logger.info(bold(__('building [%s]: ') % self.name) + summary)

14
sphinx/config.py
View File

@@ -69,15 +69,15 @@ class ENUM:
class Config:
"""Configuration file abstraction.
r"""Configuration file abstraction.
The config object makes the values of all config values available as
attributes.
It is exposed via the :py:attr:`sphinx.application.Application.config` and
:py:attr:`sphinx.environment.Environment.config` attributes. For example,
to get the value of :confval:`language`, use either ``app.config.language``
or ``env.config.language``.
It is exposed via the :py:class:`~sphinx.application.Sphinx`\ ``.config``
and :py:class:`sphinx.environment.BuildEnvironment`\ ``.config`` attributes.
For example, to get the value of :confval:`language`, use either
``app.config.language`` or ``env.config.language``.
"""
# the values are: (default, what needs to be rebuilt if changed)
@@ -132,8 +132,8 @@ class Config:
'needs_extensions': ({}, None, []),
'manpages_url': (None, 'env', []),
'nitpicky': (False, None, []),
'nitpick_ignore': ([], None, []),
'nitpick_ignore_regex': ([], None, []),
'nitpick_ignore': (set(), None, [set, list, tuple]),
'nitpick_ignore_regex': (set(), None, [set, list, tuple]),
'numfig': (False, 'env', []),
'numfig_secnum_depth': (1, 'env', []),
'numfig_format': ({}, 'env', []), # will be initialized in init_numfig_format()

15
sphinx/directives/__init__.py
View File

@@ -25,8 +25,6 @@ if TYPE_CHECKING:
nl_escape_re = re.compile(r'\\\n')
strip_backslash_re = re.compile(r'\\(.)')
T = TypeVar('T')
def optional_int(argument: str) -> int | None:
"""
@@ -41,7 +39,10 @@ def optional_int(argument: str) -> int | None:
return value
class ObjectDescription(SphinxDirective, Generic[T]):
ObjDescT = TypeVar('ObjDescT')
class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
"""
Directive to describe a class, function or similar object. Not used
directly, but subclassed (in domain-specific directives) to add custom
@@ -93,7 +94,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
else:
return [line.strip() for line in lines]
def handle_signature(self, sig: str, signode: desc_signature) -> T:
def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
"""
Parse the signature *sig* into individual nodes and append them to
*signode*. If ValueError is raised, parsing is aborted and the whole
@@ -105,7 +106,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
"""
raise ValueError
def add_target_and_index(self, name: T, sig: str, signode: desc_signature) -> None:
def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
"""
Add cross-reference IDs and entries to self.indexnode, if applicable.
@@ -168,7 +169,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
within parents in the table of contents.
An example implementations of this method is within the python domain
(:meth:`PyObject._toc_entry_name`). The python domain sets the
(:meth:`!PyObject._toc_entry_name`). The python domain sets the
``_toc_parts`` attribute within the :py:meth:`handle_signature()`
method.
"""
@@ -221,7 +222,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
node['classes'].append(self.domain)
node['classes'].append(node['objtype'])
self.names: list[T] = []
self.names: list[ObjDescT] = []
signatures = self.get_signatures()
for sig in signatures:
# add a signature node for each signature in the current unit

8
sphinx/ext/napoleon/__init__.py
View File

@@ -137,7 +137,7 @@ class Config:
See Also
--------
:attr:`napoleon_use_admonition_for_examples`
:confval:`napoleon_use_admonition_for_examples`
napoleon_use_admonition_for_references : :obj:`bool` (Defaults to False)
True to use the ``.. admonition::`` directive for **References**
@@ -145,7 +145,7 @@ class Config:
See Also
--------
:attr:`napoleon_use_admonition_for_examples`
:confval:`napoleon_use_admonition_for_examples`
napoleon_use_ivar : :obj:`bool` (Defaults to False)
True to use the ``:ivar:`` role for instance variables. False to use
@@ -203,7 +203,7 @@ class Config:
False to use a single ``:keyword arguments:`` role for all the
keywords.
This behaves similarly to :attr:`napoleon_use_param`. Note unlike
This behaves similarly to :confval:`napoleon_use_param`. Note unlike
docutils, ``:keyword:`` and ``:param:`` will not be treated the same
way - there will be a separate "Keyword Arguments" section, rendered
in the same fashion as "Parameters" section (type links created if
@@ -211,7 +211,7 @@ class Config:
See Also
--------
:attr:`napoleon_use_param`
:confval:`napoleon_use_param`
napoleon_use_rtype : :obj:`bool` (Defaults to True)
True to use the ``:rtype:`` role for the return type. False to output

2
sphinx/transforms/post_transforms/code.py
View File

@@ -26,7 +26,7 @@ class HighlightLanguageTransform(SphinxTransform):
Apply highlight_language to all literal_block nodes.
This refers both :confval:`highlight_language` setting and
:rst:dir:`highlightlang` directive. After processing, this transform
:rst:dir:`highlight` directive. After processing, this transform
removes ``highlightlang`` node from doctree.
"""
default_priority = 400

4
tests/test_config.py
View File

@@ -328,12 +328,12 @@ def test_nitpick_base(app, status, warning):
@pytest.mark.sphinx(testroot='nitpicky-warnings', confoverrides={
'nitpick_ignore': [
'nitpick_ignore': {
('py:const', 'prefix.anything.postfix'),
('py:class', 'prefix.anything'),
('py:class', 'anything.postfix'),
('js:class', 'prefix.anything.postfix'),
],
},
})
def test_nitpick_ignore(app, status, warning):
app.builder.build_all()