diff options
author | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2020-10-04 08:13:03 +0300 |
---|---|---|
committer | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2020-10-04 08:13:03 +0300 |
commit | 7f7a207626cfa62871fb315c70e88ea690f85250 (patch) | |
tree | c5785c2b42cef1687603d1c8783947a50870c39a /sphinx/application.py | |
parent | d8cb7aa4f668f1bf92458372568e1be110501eb8 (diff) |
docs: Add documentation for "override" flag of app API
Diffstat (limited to 'sphinx/application.py')
-rw-r--r-- | sphinx/application.py | 51 |
1 files changed, 49 insertions, 2 deletions
diff --git a/sphinx/application.py b/sphinx/application.py index f91027bf7..daab09058 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -471,8 +471,10 @@ class Sphinx: def add_builder(self, builder: "Type[Builder]", override: bool = False) -> None: """Register a new builder. - *builder* must be a class that inherits from - :class:`~sphinx.builders.Builder`. + *builder* must be a class that inherits from :class:`~sphinx.builders.Builder`. + + If *override* is True, the given *builder* is forcedly installed even if + a builder having the same name is already installed. .. versionchanged:: 1.8 Add *override* keyword. @@ -529,6 +531,9 @@ class Sphinx: builtin translator. This allows extensions to use custom translator and define custom nodes for the translator (see :meth:`add_node`). + If *override* is True, the given *translator_class* is forcedly installed even if + a translator for *name* is already installed. + .. versionadded:: 1.3 .. versionchanged:: 1.8 Add *override* keyword. @@ -563,6 +568,9 @@ class Sphinx: Obviously, translators for which you don't specify visitor methods will choke on the node when encountered in a document to translate. + If *override* is True, the given *node* is forcedly installed even if + a node having the same name is already installed. + .. versionchanged:: 0.5 Added the support for keyword arguments giving visit functions. """ @@ -598,6 +606,9 @@ class Sphinx: Other keyword arguments are used for node visitor functions. See the :meth:`.Sphinx.add_node` for details. + If *override* is True, the given *node* is forcedly installed even if + a node having the same name is already installed. + .. versionadded:: 1.4 """ self.registry.add_enumerable_node(node, figtype, title_getter, override=override) @@ -633,6 +644,9 @@ class Sphinx: add_directive('literalinclude', LiteralIncludeDirective) + If *override* is True, the given *cls* is forcedly installed even if + a directive named as *name* is already installed. + .. versionchanged:: 0.6 Docutils 0.5-style directive classes are now supported. .. deprecated:: 1.8 @@ -655,6 +669,9 @@ class Sphinx: <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ for more information. + If *override* is True, the given *role* is forcedly installed even if + a role named as *name* is already installed. + .. versionchanged:: 1.8 Add *override* keyword. """ @@ -670,6 +687,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. + .. versionadded:: 0.6 .. versionchanged:: 1.8 Add *override* keyword. @@ -689,6 +709,9 @@ class Sphinx: Make the given *domain* (which must be a class; more precisely, a subclass of :class:`~sphinx.domains.Domain`) known to Sphinx. + If *override* is True, the given *domain* is forcedly installed even if + a domain having the same name is already installed. + .. versionadded:: 1.0 .. versionchanged:: 1.8 Add *override* keyword. @@ -702,6 +725,9 @@ class Sphinx: Like :meth:`add_directive`, but the directive is added to the domain named *domain*. + If *override* is True, the given *directive* is forcedly installed even if + a directive named as *name* is already installed. + .. versionadded:: 1.0 .. versionchanged:: 1.8 Add *override* keyword. @@ -715,6 +741,9 @@ class Sphinx: Like :meth:`add_role`, but the role is added to the domain named *domain*. + If *override* is True, the given *role* is forcedly installed even if + a role named as *name* is already installed. + .. versionadded:: 1.0 .. versionchanged:: 1.8 Add *override* keyword. @@ -728,6 +757,9 @@ class Sphinx: Add a custom *index* class to the domain named *domain*. *index* must be a subclass of :class:`~sphinx.domains.Index`. + If *override* is True, the given *index* is forcedly installed even if + an index having the same name is already installed. + .. versionadded:: 1.0 .. versionchanged:: 1.8 Add *override* keyword. @@ -791,6 +823,9 @@ class Sphinx: For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see :ref:`xref-syntax`). + If *override* is True, the given object_type is forcedly installed even if + an object_type having the same name is already installed. + .. versionchanged:: 1.8 Add *override* keyword. """ @@ -827,6 +862,9 @@ 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. + .. versionchanged:: 1.8 Add *override* keyword. """ @@ -1022,6 +1060,9 @@ class Sphinx: new types of objects. See the source of the autodoc module for examples on how to subclass :class:`Documenter`. + If *override* is True, the given *cls* is forcedly installed even if + a documenter having the same name is already installed. + .. todo:: Add real docs for Documenter and subclassing .. versionadded:: 0.6 @@ -1070,6 +1111,9 @@ class Sphinx: Same as :confval:`source_suffix`. The users can override this using the setting. + If *override* is True, the given *suffix* is forcedly installed even if + a same suffix is already installed. + .. versionadded:: 1.8 """ self.registry.add_source_suffix(suffix, filetype, override=override) @@ -1077,6 +1121,9 @@ class Sphinx: def add_source_parser(self, *args: Any, **kwargs: Any) -> 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. + .. versionadded:: 1.4 .. versionchanged:: 1.8 *suffix* argument is deprecated. It only accepts *parser* argument. |