docs: Add documentation for "override" flag of app API

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.