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+
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 "
"https://github.com/sphinx-doc/sphinx/issues/6803")))
@ -415,7 +415,7 @@ class Sphinx:
:param event: The name of target event
:param callback: Callback function for the event
: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`.
.. versionchanged:: 3.0
@ -493,7 +493,7 @@ class Sphinx:
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``)
:param default: The default value of the configuration.
: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.
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`).
: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 override: If true, install the translator forcedly even if another translator
is already installed as the same name
@ -606,11 +606,11 @@ class Sphinx:
using :rst:role:`numref`.
:param node: A node class
:param figtype: The type of enumerable nodes. Each figtypes have individual numbering
sequences. As a system figtypes, ``figure``, ``table`` and
``code-block`` are defined. It is able to add custom nodes to these
default figtypes. It is also able to define new custom figtype if new
figtype is given.
:param figtype: The type of enumerable nodes. Each figtype has individual numbering
sequences. As system figtypes, ``figure``, ``table`` and
``code-block`` are defined. It is possible to add custom nodes to these
default figtypes. It is also possible to define new custom figtype if
a new figtype is given.
: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
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:
"""Register a Docutils directive.
:param name: The name of directive
:param name: The name of the directive
:param cls: A directive class
:param override: If true, install the directive forcedly even if another directive
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
*domain*.
:param domain: The name of target domain
:param name: A name of role
:param role: A role function
: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
@ -773,8 +773,8 @@ class Sphinx:
Add a custom *index* class to the domain named *domain*.
:param domain: The name of target domain
:param index: A index class
: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
@ -942,8 +942,8 @@ class Sphinx:
Add *filename* to the list of JavaScript files that the default HTML
template 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 priority of JavaScript file is the same as others, the JavaScript
files will be included in order of the registration. If the keyword
If the priority of the JavaScript file is the same as others, the JavaScript
files will be included in order of registration. If the keyword
argument ``body`` is given, its value will be added between the
``<script>`` tags. Extra keyword arguments are included as attributes of
the ``<script>`` tag.
@ -971,7 +971,7 @@ class Sphinx:
* - 800
- 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.
.. versionadded:: 0.5
@ -993,8 +993,8 @@ class Sphinx:
Add *filename* to the list of CSS files that the default HTML template
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
priority of CSS file is the same as others, the CSS files will be
included in order of the registration. The keyword arguments are also
priority of the CSS file is the same as others, the CSS files will be
included in order of registration. The keyword arguments are also
accepted for attributes of ``<link>`` tag.
Example::
@ -1022,15 +1022,15 @@ class Sphinx:
* - 800
- 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.
.. versionadded:: 1.0
.. versionchanged:: 1.6
Optional ``alternate`` and/or ``title`` attributes can be supplied
with the *alternate* (of boolean type) and *title* (a string)
arguments. The default is no title and *alternate* = ``False``. For
with the arguments *alternate* (a Boolean) and *title* (a string).
The default is no title and *alternate* = ``False``. For
more information, refer to the `documentation
<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.
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
loaded after ``hyperref`` package.
@ -1087,7 +1087,7 @@ class Sphinx:
Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
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
examples on how to subclass :class:`Documenter`.
@ -1140,10 +1140,10 @@ class Sphinx:
"""Register a suffix of source files.
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
a same suffix is already installed.
the same suffix is already installed.
.. versionadded:: 1.8
"""
@ -1204,8 +1204,8 @@ class Sphinx:
def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
"""Register a message catalog.
:param catalog: A name of catalog
:param locale_dir: The base path of message catalog
:param catalog: The name of the catalog
:param locale_dir: The base path of the message catalog
For more details, see :func:`sphinx.locale.get_translation()`.
@ -1216,7 +1216,7 @@ class Sphinx:
# ---- other methods -------------------------------------------------
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'``.
"""