diff options
author | Arthur Milchior <arthur@milchior.fr> | 2022-09-24 17:30:57 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-09-24 17:30:57 +0300 |
commit | 65081218ce41b1bac03de567ae8b3cde08094b72 (patch) | |
tree | 31e7ba81f7089c6b1a81254672a89a659b5a03a0 | |
parent | b842cabd4ff3613bd3d207cafd6fdea4357cba2a (diff) |
Docstring clarifications (#9877)
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>
-rw-r--r-- | sphinx/addnodes.py | 43 | ||||
-rw-r--r-- | sphinx/application.py | 90 | ||||
-rw-r--r-- | sphinx/builders/latex/transforms.py | 2 | ||||
-rw-r--r-- | sphinx/domains/std.py | 6 | ||||
-rw-r--r-- | sphinx/extension.py | 9 |
5 files changed, 85 insertions, 65 deletions
diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index e23f570d7..e22ce5fa2 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -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 """ diff --git a/sphinx/application.py b/sphinx/application.py index 565125b1e..10c03a268 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -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 diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py index e996250f7..de3f3ff03 100644 --- a/sphinx/builders/latex/transforms.py +++ b/sphinx/builders/latex/transforms.py @@ -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 diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 6218de6ab..68cab115c 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -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: diff --git a/sphinx/extension.py b/sphinx/extension.py index 356b4ab9d..2a984f5b4 100644 --- a/sphinx/extension.py +++ b/sphinx/extension.py @@ -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 |