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

Docstring clarifications (#9877)

Browse Source 
Co-authored-by: Jakob Lykke Andersen <jakobandersen@users.noreply.github.com>
Co-authored-by: Takeshi KOMIYA <i.tkomiya@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Arthur Milchior
2022-09-24 16:30:57 +02:00
committed by GitHub
parent b842cabd4f
commit 65081218ce
5 changed files with 85 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
sphinx/addnodes.py
View File

@@ -1,4 +1,4 @@
"""Additional docutils nodes."""
"""Document tree nodes that Sphinx defines on top of those in Docutils."""
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence
@@ -119,7 +119,7 @@ class toctree(nodes.General, nodes.Element, translatable):
#############################################################
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::
<pending_xref refdomain="py" reftarget="io.StringIO ...>
<pending_xref_condition condition="resolved">
@@ -471,32 +476,26 @@ class pending_xref_condition(nodes.Inline, nodes.TextElement):
<literal>
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
<reference>
<literal>
StringIO
# When resolution is failed
Otherwise, if the cross-reference resolution failed, it rewrites the
**pending_xref** as::
<reference>
<literal>
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
"""

90
sphinx/application.py
View File

@@ -639,8 +639,9 @@ class Sphinx:
: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:
@@ -687,8 +688,9 @@ class Sphinx:
: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
<https://docutils.sourceforge.io/docs/howto/rst-roles.html>`__ .
@@ -708,8 +710,9 @@ class Sphinx:
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
@@ -728,8 +731,9 @@ class Sphinx:
"""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
@@ -747,8 +751,9 @@ class Sphinx:
: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
@@ -766,8 +771,9 @@ class Sphinx:
: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
@@ -783,8 +789,9 @@ class Sphinx:
: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
@@ -889,8 +896,10 @@ class Sphinx:
(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.
@@ -949,20 +958,22 @@ class Sphinx:
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 ``<script>`` tag. See the description
of *kwargs* below.
:param priority: The priority to determine the order of ``<script>`` tag for
JavaScript files. See list of "prority range for JavaScript
files" below. If the priority of the JavaScript files it the same
as others, the JavaScript files will be loaded in order of
registration.
:param loading_method: The loading method of the JavaScript file. ``'async'`` or
``'defer'`` is allowed.
:param kwargs: Extra keyword arguments are included as attributes of the ``<script>``
tag. A special keyword argument ``body`` is given, its value will be
added between the ``<script>`` tag.
:param filename: The name of a JavaScript file that the default HTML
template will include. It must be relative to the HTML
static path, or a full URI with scheme, or ``None`` .
The ``None`` value is used to create an inline
``<script>`` tag. See the description of *kwargs*
below.
:param priority: Files are included in ascending order of priority. If
multiple JavaScript files have the same priority,
those files will be included in order of registration.
See list of "prority range for JavaScript files" below.
:param loading_method: The loading method for the JavaScript file.
Either ``'async'`` or ``'defer'`` are allowed.
:param kwargs: Extra keyword arguments are included as attributes of the
``<script>`` tag. If the special keyword argument
``body`` is given, its value will be added as the content
of the ``<script>`` tag.
Example::
@@ -1015,14 +1026,15 @@ class Sphinx:
def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
"""Register a stylesheet to include in the HTML output.
:param filename: The filename of the CSS file. It must be relative to the HTML
:param filename: The name of a CSS file that the default HTML
template will include. It must be relative to the HTML
static path, or a full URI with scheme.
:param priority: The priority to determine the order of ``<link>`` tag for the
CSS files. See list of "prority range for CSS files" below.
If the priority of the CSS files it the same as others, the
CSS files will be loaded in order of registration.
:param kwargs: Extra keyword arguments are included as attributes of the ``<link>``
tag.
:param priority: Files are included in ascending order of priority. If
multiple CSS files have the same priority,
those files will be included in order of registration.
See list of "prority range for CSS files" below.
:param kwargs: Extra keyword arguments are included as attributes of the
``<link>`` tag.
Example::
@@ -1191,8 +1203,9 @@ class Sphinx:
Same as :confval:`source_suffix`. The users can override this
using the config setting.
If *override* is True, the given *suffix* is forcedly installed even if
the same suffix is already installed.
:param override: If false, do not install it the same suffix
is already installed.
If true, unconditionally install the suffix.
.. versionadded:: 1.8
"""
@@ -1201,8 +1214,9 @@ class Sphinx:
def add_source_parser(self, parser: Type[Parser], override: bool = False) -> None:
"""Register a parser class.
If *override* is True, the given *parser* is forcedly installed even if
a parser for the same suffix is already installed.
:param override: If false, do not install it if another parser
is already installed for the same suffix.
If true, unconditionally install the parser.
.. versionadded:: 1.4
.. versionchanged:: 1.8

2
sphinx/builders/latex/transforms.py
View File

@@ -30,7 +30,7 @@ class FootnoteDocnameUpdater(SphinxTransform):
class SubstitutionDefinitionsRemover(SphinxPostTransform):
"""Remove ``substitution_definition node from doctrees."""
"""Remove ``substitution_definition`` nodes from doctrees."""
# should be invoked after Substitutions process
default_priority = Substitutions.default_priority + 1

6
sphinx/domains/std.py
View File

@@ -493,12 +493,12 @@ class ProductionList(SphinxDirective):
lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
productionGroup = ""
i = 0
first_rule_seen = False
for rule in lines:
if i == 0 and ':' not in rule:
if not first_rule_seen and ':' not in rule:
productionGroup = rule.strip()
continue
i += 1
first_rule_seen = True
try:
name, tokens = rule.split(':', 1)
except ValueError:

9
sphinx/extension.py
View File

@@ -34,7 +34,14 @@ class Extension:
def verify_needs_extensions(app: "Sphinx", config: Config) -> None:
"""Verify the required Sphinx extensions are loaded."""
"""Check that extensions mentioned in :confval:`needs_extensions` satisfy the version
requirement, and warn if an extension is not loaded.
Warns if an extension in :confval:`needs_extension` is not loaded.
:raises VersionRequirementError: if the version of an extension in
:confval:`needs_extension` is unknown or older than the required version.
"""
if config.needs_extensions is None:
return