diff options
Diffstat (limited to 'sphinx/application.py')
| -rw-r--r-- | sphinx/application.py | 90 |
1 files changed, 52 insertions, 38 deletions
diff --git a/sphinx/application.py b/sphinx/application.py index 254678569..8a349ee48 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -636,8 +636,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: @@ -684,8 +685,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>`__ . @@ -705,8 +707,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 @@ -725,8 +728,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 @@ -744,8 +748,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 @@ -763,8 +768,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 @@ -780,8 +786,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 @@ -886,8 +893,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. @@ -946,20 +955,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:: @@ -1012,14 +1023,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:: @@ -1167,8 +1179,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 """ @@ -1177,8 +1190,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 |