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

Improvements to sphinx.application docstrings

Browse Source
This commit is contained in:
Louis Maddox 2021-07-18 18:24:39 +01:00 committed by GitHub
parent de37cbcb82
commit efb6848ea9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
sphinx/application.py
View File

@ -197,7 +197,7 @@ class Sphinx:
# notice for parallel build on macOS and py38+ # notice for parallel build on macOS and py38+
if sys.version_info > (3, 8) and platform.system() == 'Darwin' and parallel > 1: if sys.version_info > (3, 8) and platform.system() == 'Darwin' and parallel > 1:
logger.info(bold(__("For security reason, parallel mode is disabled on macOS and " logger.info(bold(__("For security reasons, parallel mode is disabled on macOS and "
"python3.8 and above. For more details, please read " "python3.8 and above. For more details, please read "
"https://github.com/sphinx-doc/sphinx/issues/6803"))) "https://github.com/sphinx-doc/sphinx/issues/6803")))
@ -415,7 +415,7 @@ class Sphinx:
:param event: The name of target event :param event: The name of target event
:param callback: Callback function for the event :param callback: Callback function for the event
:param priority: The priority of the callback. The callbacks will be invoked :param priority: The priority of the callback. The callbacks will be invoked
in the order of *priority* in asending. in order of *priority* (ascending).
:return: A listener ID. It can be used for :meth:`disconnect`. :return: A listener ID. It can be used for :meth:`disconnect`.
.. versionchanged:: 3.0 .. versionchanged:: 3.0
@ -493,7 +493,7 @@ class Sphinx:
values accordingly. values accordingly.
:param name: The name of configuration value. It is recommended to be prefixed :param name: The name of the configuration value. It is recommended to be prefixed
with the extension name (ex. ``html_logo``, ``epub_title``) with the extension name (ex. ``html_logo``, ``epub_title``)
:param default: The default value of the configuration. :param default: The default value of the configuration.
:param rebuild: The condition of rebuild. It must be one of those values: :param rebuild: The condition of rebuild. It must be one of those values:
@ -539,10 +539,10 @@ class Sphinx:
"""Register or override a Docutils translator class. """Register or override a Docutils translator class.
This is used to register a custom output translator or to replace a This is used to register a custom output translator or to replace a
builtin translator. This allows extensions to use custom translator builtin translator. This allows extensions to use a custom translator
and define custom nodes for the translator (see :meth:`add_node`). and define custom nodes for the translator (see :meth:`add_node`).
:param name: The name of builder for the translator :param name: The name of the builder for the translator
:param translator_class: A translator class :param translator_class: A translator class
:param override: If true, install the translator forcedly even if another translator :param override: If true, install the translator forcedly even if another translator
is already installed as the same name is already installed as the same name
@ -606,11 +606,11 @@ class Sphinx:
using :rst:role:`numref`. using :rst:role:`numref`.
:param node: A node class :param node: A node class
:param figtype: The type of enumerable nodes. Each figtypes have individual numbering :param figtype: The type of enumerable nodes. Each figtype has individual numbering
sequences. As a system figtypes, ``figure``, ``table`` and sequences. As system figtypes, ``figure``, ``table`` and
``code-block`` are defined. It is able to add custom nodes to these ``code-block`` are defined. It is possible to add custom nodes to these
default figtypes. It is also able to define new custom figtype if new default figtypes. It is also possible to define new custom figtype if
figtype is given. a new figtype is given.
:param title_getter: A getter function to obtain the title of node. It takes an :param title_getter: A getter function to obtain the title of node. It takes an
instance of the enumerable node, and it must return its title as instance of the enumerable node, and it must return its title as
string. The title is used to the default title of references for string. The title is used to the default title of references for
@ -629,7 +629,7 @@ class Sphinx:
def add_directive(self, name: str, cls: Type[Directive], override: bool = False) -> None: def add_directive(self, name: str, cls: Type[Directive], override: bool = False) -> None:
"""Register a Docutils directive. """Register a Docutils directive.
:param name: The name of directive :param name: The name of the directive
:param cls: A directive class :param cls: A directive class
:param override: If true, install the directive forcedly even if another directive :param override: If true, install the directive forcedly even if another directive
is already installed as the same name is already installed as the same name
@ -755,9 +755,9 @@ class Sphinx:
Like :meth:`add_role`, but the role is added to the domain named Like :meth:`add_role`, but the role is added to the domain named
*domain*. *domain*.
:param domain: The name of target domain :param domain: The name of the target domain
:param name: A name of role :param name: The name of the role
:param role: A role function :param role: The role function
:param override: If true, install the role forcedly even if another role is already :param override: If true, install the role forcedly even if another role is already
installed as the same name installed as the same name
@ -773,8 +773,8 @@ class Sphinx:
Add a custom *index* class to the domain named *domain*. Add a custom *index* class to the domain named *domain*.
:param domain: The name of target domain :param domain: The name of the target domain
:param index: A index class :param index: The index class
:param override: If true, install the index forcedly even if another index is :param override: If true, install the index forcedly even if another index is
already installed as the same name already installed as the same name
@ -942,8 +942,8 @@ class Sphinx:
Add *filename* to the list of JavaScript files that the default HTML Add *filename* to the list of JavaScript files that the default HTML
template will include in order of *priority* (ascending). The filename template will include in order of *priority* (ascending). The filename
must be relative to the HTML static path , or a full URI with scheme. must be relative to the HTML static path , or a full URI with scheme.
If the priority of JavaScript file is the same as others, the JavaScript If the priority of the JavaScript file is the same as others, the JavaScript
files will be included in order of the registration. If the keyword files will be included in order of registration. If the keyword
argument ``body`` is given, its value will be added between the argument ``body`` is given, its value will be added between the
``<script>`` tags. Extra keyword arguments are included as attributes of ``<script>`` tags. Extra keyword arguments are included as attributes of
the ``<script>`` tag. the ``<script>`` tag.
@ -971,7 +971,7 @@ class Sphinx:
* - 800 * - 800
- default priority for :confval:`html_js_files` - default priority for :confval:`html_js_files`
A JavaScript file can be added to the specific HTML page when on extension A JavaScript file can be added to the specific HTML page when an extension
calls this method on :event:`html-page-context` event. calls this method on :event:`html-page-context` event.
.. versionadded:: 0.5 .. versionadded:: 0.5
@ -993,8 +993,8 @@ class Sphinx:
Add *filename* to the list of CSS files that the default HTML template Add *filename* to the list of CSS files that the default HTML template
will include in order of *priority* (ascending). The filename must be will include in order of *priority* (ascending). The filename must be
relative to the HTML static path, or a full URI with scheme. If the relative to the HTML static path, or a full URI with scheme. If the
priority of CSS file is the same as others, the CSS files will be priority of the CSS file is the same as others, the CSS files will be
included in order of the registration. The keyword arguments are also included in order of registration. The keyword arguments are also
accepted for attributes of ``<link>`` tag. accepted for attributes of ``<link>`` tag.
Example:: Example::
@ -1022,15 +1022,15 @@ class Sphinx:
* - 800 * - 800
- default priority for :confval:`html_css_files` - default priority for :confval:`html_css_files`
A CSS file can be added to the specific HTML page when on extension calls A CSS file can be added to the specific HTML page when an extension calls
this method on :event:`html-page-context` event. this method on :event:`html-page-context` event.
.. versionadded:: 1.0 .. versionadded:: 1.0
.. versionchanged:: 1.6 .. versionchanged:: 1.6
Optional ``alternate`` and/or ``title`` attributes can be supplied Optional ``alternate`` and/or ``title`` attributes can be supplied
with the *alternate* (of boolean type) and *title* (a string) with the arguments *alternate* (a Boolean) and *title* (a string).
arguments. The default is no title and *alternate* = ``False``. For The default is no title and *alternate* = ``False``. For
more information, refer to the `documentation more information, refer to the `documentation
<https://mdn.io/Web/CSS/Alternative_style_sheets>`__. <https://mdn.io/Web/CSS/Alternative_style_sheets>`__.
@ -1051,7 +1051,7 @@ class Sphinx:
r"""Register a package to include in the LaTeX source code. r"""Register a package to include in the LaTeX source code.
Add *packagename* to the list of packages that LaTeX source code will Add *packagename* to the list of packages that LaTeX source code will
include. If you provide *options*, it will be taken to `\usepackage` include. If you provide *options*, it will be taken to the `\usepackage`
declaration. If you set *after_hyperref* truthy, the package will be declaration. If you set *after_hyperref* truthy, the package will be
loaded after ``hyperref`` package. loaded after ``hyperref`` package.
@ -1087,7 +1087,7 @@ class Sphinx:
Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc` Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
extension. It must be a subclass of extension. It must be a subclass of
:class:`sphinx.ext.autodoc.Documenter`. This allows to auto-document :class:`sphinx.ext.autodoc.Documenter`. This allows auto-documenting
new types of objects. See the source of the autodoc module for 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:`Documenter`.
@ -1140,10 +1140,10 @@ class Sphinx:
"""Register a suffix of source files. """Register a suffix of source files.
Same as :confval:`source_suffix`. The users can override this Same as :confval:`source_suffix`. The users can override this
using the setting. using the config setting.
If *override* is True, the given *suffix* is forcedly installed even if If *override* is True, the given *suffix* is forcedly installed even if
a same suffix is already installed. the same suffix is already installed.
.. versionadded:: 1.8 .. versionadded:: 1.8
""" """
@ -1204,8 +1204,8 @@ class Sphinx:
def add_message_catalog(self, catalog: str, locale_dir: str) -> None: def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
"""Register a message catalog. """Register a message catalog.
:param catalog: A name of catalog :param catalog: The name of the catalog
:param locale_dir: The base path of message catalog :param locale_dir: The base path of the message catalog
For more details, see :func:`sphinx.locale.get_translation()`. For more details, see :func:`sphinx.locale.get_translation()`.
@ -1216,7 +1216,7 @@ class Sphinx:
# ---- other methods ------------------------------------------------- # ---- other methods -------------------------------------------------
def is_parallel_allowed(self, typ: str) -> bool: def is_parallel_allowed(self, typ: str) -> bool:
"""Check parallel processing is allowed or not. """Check whether parallel processing is allowed or not.
:param typ: A type of processing; ``'read'`` or ``'write'``. :param typ: A type of processing; ``'read'`` or ``'write'``.
""" """