@@ -494,31 +494,34 @@ def add_config_value(self, name: str, default: Any, rebuild: Union[bool, str],
494494 """Register a configuration value.
495495
496496 This is necessary for Sphinx to recognize new values and set default
497- values accordingly. The *name* should be prefixed with the extension
498- name, to avoid clashes. The *default* value can be any Python object.
499- The string value *rebuild* must be one of those values:
497+ values accordingly.
500498
501- * ``'env'`` if a change in the setting only takes effect when a
502- document is parsed -- this means that the whole environment must be
503- rebuilt.
504- * ``'html'`` if a change in the setting needs a full rebuild of HTML
505- documents.
506- * ``''`` if a change in the setting will not need any special rebuild.
507499
508- The *types* value takes a list of types that describes the type of
509- configuration value. For example, ``[str]`` is used to describe a
510- configuration that takes string value.
500+ :param name: The name of configuration value. It is recommended to be prefixed
501+ with the extension name (ex. ``html_logo``, ``epub_title``)
502+ :param default: The default value of the configuration.
503+ :param rebuild: The condition of rebuild. It must be one of those values:
511504
512- .. versionchanged:: 0.6
513- Changed *rebuild* from a simple boolean (equivalent to ``''`` or
514- ``'env'``) to a string. However, booleans are still accepted and
515- converted internally.
505+ * ``'env'`` if a change in the setting only takes effect when a
506+ document is parsed -- this means that the whole environment must be
507+ rebuilt.
508+ * ``'html'`` if a change in the setting needs a full rebuild of HTML
509+ documents.
510+ * ``''`` if a change in the setting will not need any special rebuild.
511+ :param types: The type of configuration value. A list of types can be specified. For
512+ example, ``[str]`` is used to describe a configuration that takes string
513+ value.
516514
517515 .. versionchanged:: 0.4
518516 If the *default* value is a callable, it will be called with the
519517 config object as its argument in order to get the default value.
520518 This can be used to implement config values whose default depends on
521519 other values.
520+
521+ .. versionchanged:: 0.6
522+ Changed *rebuild* from a simple boolean (equivalent to ``''`` or
523+ ``'env'``) to a string. However, booleans are still accepted and
524+ converted internally.
522525 """
523526 logger .debug ('[app] adding config value: %r' ,
524527 (name , default , rebuild ) + ((types ,) if types else ()))
@@ -530,6 +533,8 @@ def add_event(self, name: str) -> None:
530533 """Register an event called *name*.
531534
532535 This is needed to be able to emit it.
536+
537+ :param name: The name of the event
533538 """
534539 logger .debug ('[app] adding event: %r' , name )
535540 self .events .add (name )
@@ -560,6 +565,11 @@ def add_node(self, node: "Type[Element]", override: bool = False,
560565 This is necessary for Docutils internals. It may also be used in the
561566 future to validate nodes in the parsed documents.
562567
568+ :param node: A node class
569+ :param kwargs: Visitor functions for each builder (see below)
570+ :param override: If true, install the node forcedly even if another node is already
571+ installed as the same name
572+
563573 Node visitor functions for the Sphinx HTML, LaTeX, text and manpage
564574 writers can be given as keyword arguments: the keyword should be one or
565575 more of ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'``
@@ -581,9 +591,6 @@ def depart_math_html(self, node):
581591 Obviously, translators for which you don't specify visitor methods will
582592 choke on the node when encountered in a document to translate.
583593
584- If *override* is True, the given *node* is forcedly installed even if
585- a node having the same name is already installed.
586-
587594 .. versionchanged:: 0.5
588595 Added the support for keyword arguments giving visit functions.
589596 """
@@ -603,24 +610,21 @@ def add_enumerable_node(self, node: "Type[Element]", figtype: str,
603610 Sphinx numbers the node automatically. And then the users can refer it
604611 using :rst:role:`numref`.
605612
606- *figtype* is a type of enumerable nodes. Each figtypes have individual
607- numbering sequences. As a system figtypes, ``figure``, ``table`` and
608- ``code-block`` are defined. It is able to add custom nodes to these
609- default figtypes. It is also able to define new custom figtype if new
610- figtype is given.
611-
612- *title_getter* is a getter function to obtain the title of node. It
613- takes an instance of the enumerable node, and it must return its title
614- as string. The title is used to the default title of references for
615- :rst:role:`ref`. By default, Sphinx searches
616- ``docutils.nodes.caption`` or ``docutils.nodes.title`` from the node as
617- a title.
618-
619- Other keyword arguments are used for node visitor functions. See the
620- :meth:`.Sphinx.add_node` for details.
621-
622- If *override* is True, the given *node* is forcedly installed even if
623- a node having the same name is already installed.
613+ :param node: A node class
614+ :param figtype: The type of enumerable nodes. Each figtypes have individual numbering
615+ sequences. As a system figtypes, ``figure``, ``table`` and
616+ ``code-block`` are defined. It is able to add custom nodes to these
617+ default figtypes. It is also able to define new custom figtype if new
618+ figtype is given.
619+ :param title_getter: A getter function to obtain the title of node. It takes an
620+ instance of the enumerable node, and it must return its title as
621+ string. The title is used to the default title of references for
622+ :rst:role:`ref`. By default, Sphinx searches
623+ ``docutils.nodes.caption`` or ``docutils.nodes.title`` from the
624+ node as a title.
625+ :param kwargs: Visitor functions for each builder (same as :meth:`add_node`)
626+ :param override: If true, install the node forcedly even if another node is already
627+ installed as the same name
624628
625629 .. versionadded:: 1.4
626630 """
@@ -679,7 +683,7 @@ def add_role(self, name: str, role: Any, override: bool = False) -> None:
679683 """Register a Docutils role.
680684
681685 :param name: The name of role
682- :param cls : A role function
686+ :param role : A role function
683687 :param override: If true, install the role forcedly even if another role is already
684688 installed as the same name
685689
@@ -720,11 +724,9 @@ def add_generic_role(self, name: str, nodeclass: Any, override: bool = False) ->
720724 def add_domain (self , domain : "Type[Domain]" , override : bool = False ) -> None :
721725 """Register a domain.
722726
723- Make the given *domain* (which must be a class; more precisely, a
724- subclass of :class:`~sphinx.domains.Domain`) known to Sphinx.
725-
726- If *override* is True, the given *domain* is forcedly installed even if
727- a domain having the same name is already installed.
727+ :param domain: A domain class
728+ :param override: If true, install the domain forcedly even if another domain
729+ is already installed as the same name
728730
729731 .. versionadded:: 1.0
730732 .. versionchanged:: 1.8
@@ -739,8 +741,11 @@ def add_directive_to_domain(self, domain: str, name: str,
739741 Like :meth:`add_directive`, but the directive is added to the domain
740742 named *domain*.
741743
742- If *override* is True, the given *directive* is forcedly installed even if
743- a directive named as *name* is already installed.
744+ :param domain: The name of target domain
745+ :param name: A name of directive
746+ :param cls: A directive class
747+ :param override: If true, install the directive forcedly even if another directive
748+ is already installed as the same name
744749
745750 .. versionadded:: 1.0
746751 .. versionchanged:: 1.8
@@ -755,8 +760,11 @@ def add_role_to_domain(self, domain: str, name: str, role: Union[RoleFunction, X
755760 Like :meth:`add_role`, but the role is added to the domain named
756761 *domain*.
757762
758- If *override* is True, the given *role* is forcedly installed even if
759- a role named as *name* is already installed.
763+ :param domain: The name of target domain
764+ :param name: A name of role
765+ :param role: A role function
766+ :param override: If true, install the role forcedly even if another role is already
767+ installed as the same name
760768
761769 .. versionadded:: 1.0
762770 .. versionchanged:: 1.8
@@ -768,11 +776,12 @@ def add_index_to_domain(self, domain: str, index: "Type[Index]", override: bool
768776 ) -> None :
769777 """Register a custom index for a domain.
770778
771- Add a custom *index* class to the domain named *domain*. *index* must
772- be a subclass of :class:`~sphinx.domains.Index`.
779+ Add a custom *index* class to the domain named *domain*.
773780
774- If *override* is True, the given *index* is forcedly installed even if
775- an index having the same name is already installed.
781+ :param domain: The name of target domain
782+ :param index: A index class
783+ :param override: If true, install the index forcedly even if another index is
784+ already installed as the same name
776785
777786 .. versionadded:: 1.0
778787 .. versionchanged:: 1.8
@@ -893,6 +902,8 @@ def add_transform(self, transform: "Type[Transform]") -> None:
893902 the list of transforms that are applied after Sphinx parses a reST
894903 document.
895904
905+ :param transform: A transform class
906+
896907 .. list-table:: priority range categories for Sphinx transforms
897908 :widths: 20,80
898909
@@ -925,6 +936,8 @@ def add_post_transform(self, transform: "Type[Transform]") -> None:
925936 Add the standard docutils :class:`Transform` subclass *transform* to
926937 the list of transforms that are applied before Sphinx writes a
927938 document.
939+
940+ :param transform: A transform class
928941 """
929942 self .registry .add_post_transform (transform )
930943
@@ -1196,9 +1209,10 @@ def add_html_math_renderer(self, name: str,
11961209 def add_message_catalog (self , catalog : str , locale_dir : str ) -> None :
11971210 """Register a message catalog.
11981211
1199- The *catalog* is a name of catalog, and *locale_dir* is a base path
1200- of message catalog. For more details, see
1201- :func:`sphinx.locale.get_translation()`.
1212+ :param catalog: A name of catalog
1213+ :param locale_dir: The base path of message catalog
1214+
1215+ For more details, see :func:`sphinx.locale.get_translation()`.
12021216
12031217 .. versionadded:: 1.8
12041218 """
@@ -1209,7 +1223,7 @@ def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
12091223 def is_parallel_allowed (self , typ : str ) -> bool :
12101224 """Check parallel processing is allowed or not.
12111225
1212- `` typ`` is a type of processing; ``'read'`` or ``'write'``.
1226+ :param typ: A type of processing; ``'read'`` or ``'write'``.
12131227 """
12141228 if typ == 'read' :
12151229 attrname = 'parallel_read_safe'
0 commit comments