diff options
Diffstat (limited to 'doc/usage/restructuredtext')
| -rw-r--r-- | doc/usage/restructuredtext/basics.rst | 2 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/directives.rst | 28 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/domains.rst | 2563 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/field-lists.rst | 2 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/index.rst | 4 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/roles.rst | 282 |
6 files changed, 320 insertions, 2561 deletions
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index cc3c615..7aab544 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -289,7 +289,7 @@ information. Roles ----- -A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline +A role or "custom interpreted text role" (:dupage:`ref <roles>`) is an inline piece of explicit markup. It signifies that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 1fd5b66..ff42524 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -9,7 +9,7 @@ of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms. -See :doc:`/usage/restructuredtext/domains` for roles added by domains. +See :doc:`/usage/domains/index` for roles added by domains. .. seealso:: @@ -323,6 +323,18 @@ units as well as normal text. .. deprecated:: 3.1 Use :func:`spam` instead. +.. rst:directive:: .. versionremoved:: version + + Similar to :rst:dir:`versionadded`, but describes when the feature was removed. + An explanation may be provided to inform the reader what to use instead, + or why the feature was removed. + Example:: + + .. versionremoved:: 4.0 + The :func:`spam` function is more flexible, and should be used instead. + + .. versionadded:: 7.3 + .. rst:directive:: seealso Many sections include a list of references to module documentation or @@ -341,7 +353,7 @@ units as well as normal text. Module :py:mod:`zipfile` Documentation of the :py:mod:`zipfile` standard module. - `GNU tar manual, Basic Tar Format <http://link>`_ + `GNU tar manual, Basic Tar Format <https://link>`_ Documentation for tar archive files, including GNU tar extensions. There's also a "short form" allowed that looks like this:: @@ -544,9 +556,9 @@ __ https://pygments.org/docs/lexers def some_function(): interesting = False - print 'This line is highlighted.' - print 'This one is not...' - print '...but this one is.' + print('This line is highlighted.') + print('This one is not...') + print('...but this one is.') .. versionadded:: 1.1 .. versionchanged:: 1.6.6 @@ -576,7 +588,7 @@ __ https://pygments.org/docs/lexers :caption: this.py :name: this-py - print 'Explicit is better than implicit.' + print('Explicit is better than implicit.') In order to cross-reference a code-block using either the :rst:role:`ref` or the :rst:role:`numref` role, it is necessary @@ -881,7 +893,7 @@ Index-generating markup Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in -:doc:`/usage/restructuredtext/domains`. +:doc:`/usage/domains/index`. However, there is also explicit markup available, to make the index more comprehensive and enable index entries in documents where information is not @@ -1042,7 +1054,7 @@ Including content based on tags Undefined tags are false, defined tags (via the ``-t`` command-line option or within :file:`conf.py`, see :ref:`here <conf-tags>`) are true. Boolean - expressions, also using parentheses (like ``html and (latex or draft)``) are + expressions, also using parentheses (like ``(latex or html) and draft``) are supported. The *format* and the *name* of the current builder (``html``, ``latex`` or diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 729e651..3d9bd49 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -1,2303 +1,278 @@ -.. highlight:: rst +============== +MOVED: Domains +============== -======= -Domains -======= - -.. versionadded:: 1.0 - -Originally, Sphinx was conceived for a single project, the documentation of the -Python language. Shortly afterwards, it was made available for everyone as a -documentation tool, but the documentation of Python modules remained deeply -built in -- the most fundamental directives, like ``function``, were designed -for Python objects. Since Sphinx has become somewhat popular, interest -developed in using it for many different purposes: C/C++ projects, JavaScript, -or even reStructuredText markup (like in this documentation). - -While this was always possible, it is now much easier to easily support -documentation of projects using different programming languages or even ones -not supported by the main Sphinx distribution, by providing a **domain** for -every such purpose. - -A domain is a collection of markup (reStructuredText :term:`directive`\ s and -:term:`role`\ s) to describe and link to :term:`object`\ s belonging together, -e.g. elements of a programming language. Directive and role names in a domain -have names like ``domain:name``, e.g. ``py:function``. Domains can also -provide custom indices (like the Python Module Index). - -Having domains means that there are no naming problems when one set of -documentation wants to refer to e.g. C++ and Python classes. It also means -that extensions that support the documentation of whole new languages are much -easier to write. - -This section describes what the domains that are included with Sphinx provide. -The domain API is documented as well, in the section :ref:`domain-api`. - - -.. _basic-domain-markup: - -Basic Markup ------------- - -Most domains provide a number of :dfn:`object description directives`, used to -describe specific objects provided by modules. Each directive requires one or -more signatures to provide basic information about what is being described, and -the content should be the description. - -A domain will typically keep an internal index of all entities to aid -cross-referencing. -Typically it will also add entries in the shown general index. -If you want to suppress the addition of an entry in the shown index, you can -give the directive option flag ``:no-index-entry:``. -If you want to exclude the object description from the table of contents, you -can give the directive option flag ``:no-contents-entry:``. -If you want to typeset an object description, without even making it available -for cross-referencing, you can give the directive option flag ``:no-index:`` -(which implies ``:no-index-entry:``). -If you do not want to typeset anything, you can give the directive option flag -``:no-typesetting:``. This can for example be used to create only a target and -index entry for later reference. -Though, note that not every directive in every domain may support these -options. - -.. versionadded:: 3.2 - The directive option ``noindexentry`` in the Python, C, C++, and Javascript - domains. - -.. versionadded:: 5.2.3 - The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript, - and reStructuredText domains. - -.. versionadded:: 7.2 - The directive option ``no-typesetting`` in the Python, C, C++, Javascript, - and reStructuredText domains. - -.. versionchanged:: 7.2 - - * The directive option ``:noindex:`` was renamed - to ``:no-index:``. - * The directive option ``:noindexentry:`` was renamed - to ``:no-index-entry:``. - * The directive option ``:nocontentsentry:`` was renamed - to ``:no-contents-entry:``. - - The previous names are retained as aliases, - but will be deprecated and removed - in a future version of Sphinx. - -An example using a Python domain directive:: - - .. py:function:: spam(eggs) - ham(eggs) - - Spam or ham the foo. - -This describes the two Python functions ``spam`` and ``ham``. (Note that when -signatures become too long, you can break them if you add a backslash to lines -that are continued in the next line. Example:: - - .. py:function:: filterwarnings(action, message='', category=Warning, \ - module='', lineno=0, append=False) - :no-index: - -(This example also shows how to use the ``:no-index:`` flag.) - -The domains also provide roles that link back to these object descriptions. -For example, to link to one of the functions described in the example above, -you could say :: - - The function :py:func:`spam` does a similar thing. - -As you can see, both directive and role names contain the domain name and the -directive name. - -The directive option ``:no-typesetting:`` can be used to create a target -(and index entry) which can later be referenced -by the roles provided by the domain. -This is particularly useful for literate programming: - -.. code-block:: rst - - .. py:function:: spam(eggs) - :no-typesetting: - - .. code:: - - def spam(eggs): - pass - - The function :py:func:`spam` does nothing. - -.. rubric:: Default Domain - -For documentation describing objects from solely one domain, authors will not -have to state again its name at each directive, role, etc... after -having specified a default. This can be done either via the config -value :confval:`primary_domain` or via this directive: - -.. rst:directive:: .. default-domain:: name - - Select a new default domain. While the :confval:`primary_domain` selects a - global default, this only has an effect within the same file. - -If no other default is selected, the Python domain (named ``py``) is the -default one, mostly for compatibility with documentation written for older -versions of Sphinx. - -Directives and roles that belong to the default domain can be mentioned without -giving the domain name, i.e. :: - - .. function:: pyfunc() - - Describes a Python function. - - Reference to :func:`pyfunc`. - -Cross-referencing syntax -~~~~~~~~~~~~~~~~~~~~~~~~ - -For cross-reference roles provided by domains, the same facilities exist as for -general cross-references. See :ref:`xref-syntax`. - -In short: - -* You may supply an explicit title and reference target: ``:role:`title - <target>``` will refer to *target*, but the link text will be *title*. - -* If you prefix the content with ``!``, no reference/hyperlink will be created. - -* If you prefix the content with ``~``, the link text will only be the last - component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will - refer to ``Queue.Queue.get`` but only display ``get`` as the link text. - -.. _python-domain: - -The Python Domain ------------------ - -The Python domain (name **py**) provides the following directives for module -declarations: - -.. rst:directive:: .. py:module:: name - - This directive marks the beginning of the description of a module (or package - submodule, in which case the name should be fully qualified, including the - package name). A description of the module such as the docstring can be - placed in the body of the directive. - - This directive will also cause an entry in the global module index. - - .. versionchanged:: 5.2 - - Module directives support body content. - - .. rubric:: options - - .. rst:directive:option:: platform: platforms - :type: comma separated list - - Indicate platforms which the module is available (if it is available on - all platforms, the option should be omitted). The keys are short - identifiers; examples that are in use include "IRIX", "Mac", "Windows" - and "Unix". It is important to use a key which has already been used when - applicable. - - .. rst:directive:option:: synopsis: purpose - :type: text - - Consist of one sentence describing the module's purpose -- it is currently - only used in the Global Module Index. - - .. rst:directive:option:: deprecated - :type: no argument - - Mark a module as deprecated; it will be designated as such in various - locations then. - - - -.. rst:directive:: .. py:currentmodule:: name - - This directive tells Sphinx that the classes, functions etc. documented from - here are in the given module (like :rst:dir:`py:module`), but it will not - create index entries, an entry in the Global Module Index, or a link target - for :rst:role:`py:mod`. This is helpful in situations where documentation - for things in a module is spread over multiple files or sections -- one - location has the :rst:dir:`py:module` directive, the others only - :rst:dir:`py:currentmodule`. - -The following directives are provided for module and class contents: - -.. rst:directive:: .. py:function:: name(parameters) - .. py:function:: name[type parameters](parameters) - - Describes a module-level function. - The signature should include the parameters, - together with optional type parameters, - as given in the Python function definition, see :ref:`signatures`. - For example:: - - .. py:function:: Timer.repeat(repeat=3, number=1_000_000) - .. py:function:: add[T](a: T, b: T) -> T - - For methods you should use :rst:dir:`py:method`. - - The description normally includes information about the parameters required - and how they are used (especially whether mutable objects passed as - parameters are modified), side effects, and possible exceptions. - - This information can (in any ``py`` directive) optionally be given in a - structured form, see :ref:`info-field-lists`. - - .. rubric:: options - - .. rst:directive:option:: async - :type: no value - - Indicate the function is an async function. - - .. versionadded:: 2.1 - - .. rst:directive:option:: canonical - :type: full qualified name including module name - - Describe the location where the object is defined if the object is - imported from other modules - - .. versionadded:: 4.0 - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's arguments will be emitted on a single logical - line, overriding :confval:`python_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - - .. rst:directive:option:: single-line-type-parameter-list - :type: no value - - Ensure that the function's type parameters are emitted on a single - logical line, overriding :confval:`python_maximum_signature_line_length` - and :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - - -.. rst:directive:: .. py:data:: name - - Describes global data in a module, including both variables and values used - as "defined constants." Class and object attributes are not documented - using this environment. - - .. rubric:: options - - .. rst:directive:option:: type: type of the variable - :type: text - - .. versionadded:: 2.4 - - .. rst:directive:option:: value: initial value of the variable - :type: text - - .. versionadded:: 2.4 - - .. rst:directive:option:: canonical - :type: full qualified name including module name - - Describe the location where the object is defined if the object is - imported from other modules - - .. versionadded:: 4.0 - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - -.. rst:directive:: .. py:exception:: name - .. py:exception:: name(parameters) - .. py:exception:: name[type parmeters](parameters) - - Describes an exception class. - The signature can, but need not include parentheses with constructor arguments, - or may optionally include type parameters (see :pep:`695`). - - .. rubric:: options - - .. rst:directive:option:: final - :type: no value - - Indicate the class is a final class. - - .. versionadded:: 3.1 - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - See :rst:dir:`py:class:single-line-parameter-list`. - - .. versionadded:: 7.1 - - .. rst:directive:option:: single-line-type-parameter-list - :type: no value - - See :rst:dir:`py:class:single-line-type-parameter-list`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. py:class:: name - .. py:class:: name(parameters) - .. py:class:: name[type parmeters](parameters) - - Describes a class. - The signature can optionally include type parameters (see :pep:`695`) - or parentheses with parameters which will be shown as the constructor arguments. - See also :ref:`signatures`. - - Methods and attributes belonging to the class should be placed in this - directive's body. If they are placed outside, the supplied name should - contain the class name so that cross-references still work. Example:: - - .. py:class:: Foo - - .. py:method:: quux() - - -- or -- - - .. py:class:: Bar - - .. py:method:: Bar.quux() - - The first way is the preferred one. - - .. rubric:: options - - .. rst:directive:option:: canonical - :type: full qualified name including module name - - Describe the location where the object is defined if the object is - imported from other modules - - .. versionadded:: 4.0 - - .. rst:directive:option:: final - :type: no value - - Indicate the class is a final class. - - .. versionadded:: 3.1 - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the class constructor's arguments will be emitted on a single - logical line, overriding :confval:`python_maximum_signature_line_length` - and :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - - .. rst:directive:option:: single-line-type-parameter-list - :type: no value - - Ensure that the class type parameters are emitted on a single logical - line, overriding :confval:`python_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - -.. rst:directive:: .. py:attribute:: name - - Describes an object data attribute. The description should include - information about the type of the data to be expected and whether it may be - changed directly. - - .. rubric:: options - - .. rst:directive:option:: type: type of the attribute - :type: text - - .. versionadded:: 2.4 - - .. rst:directive:option:: value: initial value of the attribute - :type: text - - .. versionadded:: 2.4 - - .. rst:directive:option:: canonical - :type: full qualified name including module name - - Describe the location where the object is defined if the object is - imported from other modules - - .. versionadded:: 4.0 - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - -.. rst:directive:: .. py:property:: name - - Describes an object property. - - .. versionadded:: 4.0 - - .. rubric:: options - - .. rst:directive:option:: abstractmethod - :type: no value - - Indicate the property is abstract. - - .. rst:directive:option:: classmethod - :type: no value - - Indicate the property is a classmethod. - - .. versionaddedd: 4.2 - - .. rst:directive:option:: type: type of the property - :type: text - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - -.. rst:directive:: .. py:method:: name(parameters) - .. py:method:: name[type parameters](parameters) - - Describes an object method. The parameters should not include the ``self`` - parameter. The description should include similar information to that - described for ``function``. See also :ref:`signatures` and - :ref:`info-field-lists`. - - .. rubric:: options - - .. rst:directive:option:: abstractmethod - :type: no value - - Indicate the method is an abstract method. - - .. versionadded:: 2.1 - - .. rst:directive:option:: async - :type: no value - - Indicate the method is an async method. - - .. versionadded:: 2.1 - - .. rst:directive:option:: canonical - :type: full qualified name including module name - - Describe the location where the object is defined if the object is - imported from other modules - - .. versionadded:: 4.0 - - .. rst:directive:option:: classmethod - :type: no value - - Indicate the method is a class method. - - .. versionadded:: 2.1 - - .. rst:directive:option:: final - :type: no value - - Indicate the class is a final method. - - .. versionadded:: 3.1 - - .. rst::directive:option:: module - :type: text - - Describe the location where the object is defined. The default value is - the module specified by :rst:dir:`py:currentmodule`. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the method's arguments will be emitted on a single logical - line, overriding :confval:`python_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - - .. rst:directive:option:: single-line-type-parameter-list - :type: no value - - Ensure that the method's type parameters are emitted on a single logical - line, overriding :confval:`python_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.2 - - .. rst:directive:option:: staticmethod - :type: no value - - Indicate the method is a static method. - - .. versionadded:: 2.1 - - -.. rst:directive:: .. py:staticmethod:: name(parameters) - .. py:staticmethod:: name[type parameters](parameters) - - Like :rst:dir:`py:method`, but indicates that the method is a static method. - - .. versionadded:: 0.4 - -.. rst:directive:: .. py:classmethod:: name(parameters) - .. py:classmethod:: name[type parameters](parameters) - - Like :rst:dir:`py:method`, but indicates that the method is a class method. - - .. versionadded:: 0.6 - -.. rst:directive:: .. py:decorator:: name - .. py:decorator:: name(parameters) - .. py:decorator:: name[type parameters](parameters) - - Describes a decorator function. The signature should represent the usage as - a decorator. For example, given the functions - - .. code-block:: python - - def removename(func): - func.__name__ = '' - return func - - def setnewname(name): - def decorator(func): - func.__name__ = name - return func - return decorator - - the descriptions should look like this:: - - .. py:decorator:: removename - - Remove name of the decorated function. - - .. py:decorator:: setnewname(name) - - Set name of the decorated function to *name*. - - (as opposed to ``.. py:decorator:: removename(func)``.) - - There is no ``py:deco`` role to link to a decorator that is marked up with - this directive; rather, use the :rst:role:`py:func` role. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the decorator's arguments will be emitted on a single logical - line, overriding :confval:`python_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - - .. rst:directive:option:: single-line-type-parameter-list - :type: no value - - Ensure that the decorator's type parameters are emitted on a single - logical line, overriding :confval:`python_maximum_signature_line_length` - and :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.2 - -.. rst:directive:: .. py:decoratormethod:: name - .. py:decoratormethod:: name(signature) - .. py:decoratormethod:: name[type parameters](signature) - - Same as :rst:dir:`py:decorator`, but for decorators that are methods. - - Refer to a decorator method using the :rst:role:`py:meth` role. - -.. _signatures: - -Python Signatures -~~~~~~~~~~~~~~~~~ - -Signatures of functions, methods and class constructors can be given like they -would be written in Python. - -Default values for optional arguments can be given (but if they contain commas, -they will confuse the signature parser). Python 3-style argument annotations -can also be given as well as return type annotations:: - - .. py:function:: compile(source : string, filename, symbol='file') -> ast object - -For functions with optional parameters that don't have default values -(typically functions implemented in C extension modules without keyword -argument support), you can use brackets to specify the optional parts: - -.. py:function:: compile(source[, filename[, symbol]]) - :no-index: - -It is customary to put the opening bracket before the comma. - -Python 3.12 introduced *type parameters*, which are type variables -declared directly within the class or function definition: - -.. code:: python - - class AnimalList[AnimalT](list[AnimalT]): - ... - - def add[T](a: T, b: T) -> T: - return a + b - -The corresponding reStructuredText documentation would be: - -.. code:: rst - - .. py:class:: AnimalList[AnimalT] - - .. py:function:: add[T](a: T, b: T) -> T - -See :pep:`695` and :pep:`696` for details and the full specification. - -.. _info-field-lists: - -Info field lists -~~~~~~~~~~~~~~~~ - -.. versionadded:: 0.4 -.. versionchanged:: 3.0 - - meta fields are added. - -Inside Python object description directives, reST field lists with these fields -are recognized and formatted nicely: - -* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``: - Description of a parameter. -* ``type``: Type of a parameter. Creates a link if possible. -* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific - exception is raised. -* ``var``, ``ivar``, ``cvar``: Description of a variable. -* ``vartype``: Type of a variable. Creates a link if possible. -* ``returns``, ``return``: Description of the return value. -* ``rtype``: Return type. Creates a link if possible. -* ``meta``: Add metadata to description of the python object. The metadata will - not be shown on output document. For example, ``:meta private:`` indicates - the python object is private member. It is used in - :py:mod:`sphinx.ext.autodoc` for filtering members. - -.. note:: - - In current release, all ``var``, ``ivar`` and ``cvar`` are represented as - "Variable". There is no difference at all. - -The field names must consist of one of these keywords and an argument (except -for ``returns`` and ``rtype``, which do not need an argument). This is best -explained by an example:: - - .. py:function:: send_message(sender, recipient, message_body, [priority=1]) - - Send a message to a recipient - - :param str sender: The person sending the message - :param str recipient: The recipient of the message - :param str message_body: The body of the message - :param priority: The priority of the message, can be a number 1-5 - :type priority: integer or None - :return: the message id - :rtype: int - :raises ValueError: if the message_body exceeds 160 characters - :raises TypeError: if the message_body is not a basestring - -This will render like this: - -.. py:function:: send_message(sender, recipient, message_body, [priority=1]) - :no-index: - - Send a message to a recipient - - :param str sender: The person sending the message - :param str recipient: The recipient of the message - :param str message_body: The body of the message - :param priority: The priority of the message, can be a number 1-5 - :type priority: int or None - :return: the message id - :rtype: int - :raises ValueError: if the message_body exceeds 160 characters - :raises TypeError: if the message_body is not a basestring - -It is also possible to combine parameter type and description, if the type is a -single word, like this:: - - :param int priority: The priority of the message, can be a number 1-5 - -.. versionadded:: 1.5 - -Container types such as lists and dictionaries can be linked automatically -using the following syntax:: - - :type priorities: list(int) - :type priorities: list[int] - :type mapping: dict(str, int) - :type mapping: dict[str, int] - :type point: tuple(float, float) - :type point: tuple[float, float] - -Multiple types in a type field will be linked automatically if separated by the -word "or":: - - :type an_arg: int or None - :vartype a_var: str or int - :rtype: float or str - -.. _python-roles: - -Cross-referencing Python objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following roles refer to objects in modules and are possibly hyperlinked if -a matching identifier is found: - -.. rst:role:: py:mod - - Reference a module; a dotted name may be used. This should also be used for - package names. - -.. rst:role:: py:func - - Reference a Python function; dotted names may be used. The role text needs - not include trailing parentheses to enhance readability; they will be added - automatically by Sphinx if the :confval:`add_function_parentheses` config - value is ``True`` (the default). - -.. rst:role:: py:data - - Reference a module-level variable. - -.. rst:role:: py:const - - Reference a "defined" constant. This may be a Python variable that is not - intended to be changed. - -.. rst:role:: py:class - - Reference a class; a dotted name may be used. - -.. rst:role:: py:meth - - Reference a method of an object. The role text can include the type name - and the method name; if it occurs within the description of a type, the type - name can be omitted. A dotted name may be used. - -.. rst:role:: py:attr - - Reference a data attribute of an object. - - .. note:: The role is also able to refer to property. - -.. rst:role:: py:exc - - Reference an exception. A dotted name may be used. - -.. rst:role:: py:obj - - Reference an object of unspecified type. Useful e.g. as the - :confval:`default_role`. - - .. versionadded:: 0.4 - -The name enclosed in this markup can include a module name and/or a class name. -For example, ``:py:func:`filter``` could refer to a function named ``filter`` -in the current module, or the built-in function of that name. In contrast, -``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the -``foo`` module. - -Normally, names in these roles are searched first without any further -qualification, then with the current module name prepended, then with the -current module and class name (if any) prepended. If you prefix the name with -a dot, this order is reversed. For example, in the documentation of Python's -:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in -function, while ``:py:func:`.open``` refers to :func:`codecs.open`. - -A similar heuristic is used to determine whether the name is an attribute of -the currently documented class. - -Also, if the name is prefixed with a dot, and no exact match is found, the -target is taken as a suffix and all object names with that suffix are searched. -For example, ``:py:meth:`.TarFile.close``` references the -``tarfile.TarFile.close()`` function, even if the current module is not -``tarfile``. Since this can get ambiguous, if there is more than one possible -match, you will get a warning from Sphinx. - -Note that you can combine the ``~`` and ``.`` prefixes: -``:py:meth:`~.TarFile.close``` will reference the ``tarfile.TarFile.close()`` -method, but the visible link caption will only be ``close()``. - - -.. _c-domain: - -The C Domain ------------- - -The C domain (name **c**) is suited for documentation of C API. - -.. rst:directive:: .. c:member:: declaration - .. c:var:: declaration - - Describes a C struct member or variable. Example signature:: - - .. c:member:: PyObject *PyTypeObject.tp_bases - - The difference between the two directives is only cosmetic. - -.. rst:directive:: .. c:function:: function prototype - - Describes a C function. The signature should be given as in C, e.g.:: - - .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - Note that you don't have to backslash-escape asterisks in the signature, as - it is not parsed by the reST inliner. - - In the description of a function you can use the following info fields - (see also :ref:`info-field-lists`). - - * ``param``, ``parameter``, ``arg``, ``argument``, - Description of a parameter. - * ``type``: Type of a parameter, - written as if passed to the :rst:role:`c:expr` role. - * ``returns``, ``return``: Description of the return value. - * ``rtype``: Return type, - written as if passed to the :rst:role:`c:expr` role. - * ``retval``, ``retvals``: An alternative to ``returns`` for describing - the result of the function. - - .. versionadded:: 4.3 - The ``retval`` field type. - - For example:: - - .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - :param type: description of the first parameter. - :param nitems: description of the second parameter. - :returns: a result. - :retval NULL: under some conditions. - :retval NULL: under some other conditions as well. - - which renders as - - .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - .. - ** for some editors (e.g., vim) to stop bold-highlighting the source - - :param type: description of the first parameter. - :param nitems: description of the second parameter. - :returns: a result. - :retval NULL: under some conditions. - :retval NULL: under some other conditions as well. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's parameters will be emitted on a single logical - line, overriding :confval:`c_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - - -.. rst:directive:: .. c:macro:: name - .. c:macro:: name(arg list) - - Describes a C macro, i.e., a C-language ``#define``, without the replacement - text. - - In the description of a macro you can use the same info fields as for the - :rst:dir:`c:function` directive. - - .. versionadded:: 3.0 - The function style variant. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the macro's parameters will be emitted on a single logical - line, overriding :confval:`c_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. c:struct:: name - - Describes a C struct. - - .. versionadded:: 3.0 - -.. rst:directive:: .. c:union:: name - - Describes a C union. - - .. versionadded:: 3.0 - -.. rst:directive:: .. c:enum:: name - - Describes a C enum. - - .. versionadded:: 3.0 - -.. rst:directive:: .. c:enumerator:: name - - Describes a C enumerator. - - .. versionadded:: 3.0 - -.. rst:directive:: .. c:type:: typedef-like declaration - .. c:type:: name - - Describes a C type, either as a typedef, or the alias for an unspecified - type. - -.. _c-roles: - -Cross-referencing C constructs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following roles create cross-references to C-language constructs if they -are defined in the documentation: - -.. rst:role:: c:member - c:data - c:var - c:func - c:macro - c:struct - c:union - c:enum - c:enumerator - c:type - - Reference a C declaration, as defined above. - Note that :rst:role:`c:member`, :rst:role:`c:data`, and - :rst:role:`c:var` are equivalent. - - .. versionadded:: 3.0 - The var, struct, union, enum, and enumerator roles. - - -Anonymous Entities -~~~~~~~~~~~~~~~~~~ - -C supports anonymous structs, enums, and unions. -For the sake of documentation they must be given some name that starts with -``@``, e.g., ``@42`` or ``@data``. -These names can also be used in cross-references, -though nested symbols will be found even when omitted. -The ``@...`` name will always be rendered as **[anonymous]** (possibly as a -link). - -Example:: - - .. c:struct:: Data - - .. c:union:: @data - - .. c:var:: int a - - .. c:var:: double b - - Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. - -This will be rendered as: - -.. c:struct:: Data - :no-contents-entry: - :no-index-entry: - - .. c:union:: @data - :no-contents-entry: - :no-index-entry: - - .. c:var:: int a - :no-contents-entry: - :no-index-entry: - - .. c:var:: double b - :no-contents-entry: - :no-index-entry: - -Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. - -.. versionadded:: 3.0 - - -Aliasing Declarations -~~~~~~~~~~~~~~~~~~~~~ - -.. c:namespace-push:: @alias - -Sometimes it may be helpful list declarations elsewhere than their main -documentation, e.g., when creating a synopsis of an interface. -The following directive can be used for this purpose. - -.. rst:directive:: .. c:alias:: name - - Insert one or more alias declarations. Each entity can be specified - as they can in the :rst:role:`c:any` role. - - For example:: - - .. c:var:: int data - .. c:function:: int f(double k) - - .. c:alias:: data - f - - becomes - - .. c:var:: int data - .. c:function:: int f(double k) - - .. c:alias:: data - f - - .. versionadded:: 3.2 - - - .. rubric:: Options - - .. rst:directive:option:: maxdepth: int - - Insert nested declarations as well, up to the total depth given. - Use 0 for infinite depth and 1 for just the mentioned declaration. - Defaults to 1. - - .. versionadded:: 3.3 - - .. rst:directive:option:: noroot - - Skip the mentioned declarations and only render nested declarations. - Requires ``maxdepth`` either 0 or at least 2. - - .. versionadded:: 3.5 - - -.. c:namespace-pop:: - - -Inline Expressions and Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. rst:role:: c:expr - c:texpr - - Insert a C expression or type either as inline code (``cpp:expr``) - or inline text (``cpp:texpr``). For example:: - - .. c:var:: int a = 42 - - .. c:function:: int f(int i) - - An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). - - A type: :c:expr:`const Data*` - (or as text :c:texpr:`const Data*`). - - will be rendered as follows: - - .. c:var:: int a = 42 - :no-contents-entry: - :no-index-entry: - - .. c:function:: int f(int i) - :no-contents-entry: - :no-index-entry: - - An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). - - A type: :c:expr:`const Data*` - (or as text :c:texpr:`const Data*`). - - .. versionadded:: 3.0 - - -Namespacing -~~~~~~~~~~~ - -.. versionadded:: 3.1 - -The C language it self does not support namespacing, but it can sometimes be -useful to emulate it in documentation, e.g., to show alternate declarations. -The feature may also be used to document members of structs/unions/enums -separate from their parent declaration. - -The current scope can be changed using three namespace directives. They manage -a stack declarations where ``c:namespace`` resets the stack and changes a given -scope. - -The ``c:namespace-push`` directive changes the scope to a given inner scope -of the current one. - -The ``c:namespace-pop`` directive undoes the most recent -``c:namespace-push`` directive. - -.. rst:directive:: .. c:namespace:: scope specification - - Changes the current scope for the subsequent objects to the given scope, and - resets the namespace directive stack. Note that nested scopes can be - specified by separating with a dot, e.g.:: - - .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct - - All subsequent objects will be defined as if their name were declared with - the scope prepended. The subsequent cross-references will be searched for - starting in the current scope. - - Using ``NULL`` or ``0`` as the scope will change to global scope. - -.. rst:directive:: .. c:namespace-push:: scope specification - - Change the scope relatively to the current scope. For example, after:: - - .. c:namespace:: A.B - - .. c:namespace-push:: C.D - - the current scope will be ``A.B.C.D``. - -.. rst:directive:: .. c:namespace-pop:: - - Undo the previous ``c:namespace-push`` directive (*not* just pop a scope). - For example, after:: - - .. c:namespace:: A.B - - .. c:namespace-push:: C.D - - .. c:namespace-pop:: - - the current scope will be ``A.B`` (*not* ``A.B.C``). - - If no previous ``c:namespace-push`` directive has been used, but only a - ``c:namespace`` directive, then the current scope will be reset to global - scope. That is, ``.. c:namespace:: A.B`` is equivalent to:: - - .. c:namespace:: NULL - - .. c:namespace-push:: A.B - -Configuration Variables -~~~~~~~~~~~~~~~~~~~~~~~ - -See :ref:`c-config`. - - -.. _cpp-domain: - -The C++ Domain --------------- - -The C++ domain (name **cpp**) supports documenting C++ projects. - -Directives for Declaring Entities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following directives are available. All declarations can start with a -visibility statement (``public``, ``private`` or ``protected``). - -.. rst:directive:: .. cpp:class:: class specifier - .. cpp:struct:: class specifier - - Describe a class/struct, possibly with specification of inheritance, e.g.,:: - - .. cpp:class:: MyClass : public MyBase, MyOtherBase - - The difference between :rst:dir:`cpp:class` and :rst:dir:`cpp:struct` is - only cosmetic: the prefix rendered in the output, and the specifier shown - in the index. - - The class can be directly declared inside a nested scope, e.g.,:: - - .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase - - A class template can be declared:: - - .. cpp:class:: template<typename T, std::size_t N> std::array - - or with a line break:: - - .. cpp:class:: template<typename T, std::size_t N> \ - std::array - - Full and partial template specialisations can be declared:: - - .. cpp:class:: template<> \ - std::array<bool, 256> - - .. cpp:class:: template<typename T> \ - std::array<T, 42> - - .. versionadded:: 2.0 - The :rst:dir:`cpp:struct` directive. - -.. rst:directive:: .. cpp:function:: (member) function prototype - - Describe a function or member function, e.g.,:: - - .. cpp:function:: bool myMethod(int arg1, std::string arg2) - - A function with parameters and types. - - .. cpp:function:: bool myMethod(int, double) - - A function with unnamed parameters. - - .. cpp:function:: const T &MyClass::operator[](std::size_t i) const - - An overload for the indexing operator. - - .. cpp:function:: operator bool() const - - A casting operator. - - .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept - - A constexpr function. - - .. cpp:function:: MyClass::MyClass(const MyClass&) = default - - A copy constructor with default implementation. - - Function templates can also be described:: - - .. cpp:function:: template<typename U> \ - void print(U &&u) - - and function template specialisations:: - - .. cpp:function:: template<> \ - void print(int i) - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's parameters will be emitted on a single logical - line, overriding :confval:`cpp_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. cpp:member:: (member) variable declaration - .. cpp:var:: (member) variable declaration - - Describe a variable or member variable, e.g.,:: - - .. cpp:member:: std::string MyClass::myMember - - .. cpp:var:: std::string MyClass::myOtherMember[N][M] - - .. cpp:member:: int a = 42 - - Variable templates can also be described:: - - .. cpp:member:: template<class T> \ - constexpr T pi = T(3.1415926535897932385) - -.. rst:directive:: .. cpp:type:: typedef declaration - .. cpp:type:: name - .. cpp:type:: type alias declaration - - Describe a type as in a typedef declaration, a type alias declaration, or - simply the name of a type with unspecified type, e.g.,:: - - .. cpp:type:: std::vector<int> MyList - - A typedef-like declaration of a type. - - .. cpp:type:: MyContainer::const_iterator - - Declaration of a type alias with unspecified type. - - .. cpp:type:: MyType = std::unordered_map<int, std::string> - - Declaration of a type alias. - - A type alias can also be templated:: - - .. cpp:type:: template<typename T> \ - MyContainer = std::vector<T> - - The example are rendered as follows. - - .. cpp:type:: std::vector<int> MyList - :no-contents-entry: - :no-index-entry: - - A typedef-like declaration of a type. - - .. cpp:type:: MyContainer::const_iterator - :no-contents-entry: - :no-index-entry: - - Declaration of a type alias with unspecified type. - - .. cpp:type:: MyType = std::unordered_map<int, std::string> - :no-contents-entry: - :no-index-entry: - - Declaration of a type alias. - - .. cpp:type:: template<typename T> \ - MyContainer = std::vector<T> - :no-contents-entry: - :no-index-entry: - -.. rst:directive:: .. cpp:enum:: unscoped enum declaration - .. cpp:enum-struct:: scoped enum declaration - .. cpp:enum-class:: scoped enum declaration - - Describe a (scoped) enum, possibly with the underlying type specified. Any - enumerators declared inside an unscoped enum will be declared both in the - enum scope and in the parent scope. Examples:: - - .. cpp:enum:: MyEnum - - An unscoped enum. - - .. cpp:enum:: MySpecificEnum : long - - An unscoped enum with specified underlying type. - - .. cpp:enum-class:: MyScopedEnum - - A scoped enum. - - .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type - - A scoped enum with non-default visibility, and with a specified - underlying type. - -.. rst:directive:: .. cpp:enumerator:: name - .. cpp:enumerator:: name = constant - - Describe an enumerator, optionally with its value defined, e.g.,:: - - .. cpp:enumerator:: MyEnum::myEnumerator - - .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42 - -.. rst:directive:: .. cpp:union:: name - - Describe a union. - - .. versionadded:: 1.8 - -.. rst:directive:: .. cpp:concept:: template-parameter-list name - - .. warning:: The support for concepts is experimental. It is based on the - current draft standard and the Concepts Technical Specification. - The features may change as they evolve. - - Describe a concept. It must have exactly 1 template parameter list. The name - may be a nested name. Example:: - - .. cpp:concept:: template<typename It> std::Iterator - - Proxy to an element of a notional sequence that can be compared, - indirected, or incremented. - - **Notation** - - .. cpp:var:: It r - - An lvalue. - - **Valid Expressions** - - - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable. - - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when - :cpp:expr:`r` is incrementable. - - This will render as follows: - - .. cpp:concept:: template<typename It> std::Iterator - - Proxy to an element of a notional sequence that can be compared, - indirected, or incremented. - - **Notation** - - .. cpp:var:: It r - - An lvalue. - - **Valid Expressions** - - - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable. - - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` - is incrementable. - - .. versionadded:: 1.5 - - -Options -^^^^^^^ - -Some directives support options: - -- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`. -- ``:tparam-line-spec:``, for templated declarations. - If specified, each template parameter will be rendered on a separate line. - - .. versionadded:: 1.6 - -Anonymous Entities -~~~~~~~~~~~~~~~~~~ - -C++ supports anonymous namespaces, classes, enums, and unions. -For the sake of documentation they must be given some name that starts with -``@``, e.g., ``@42`` or ``@data``. -These names can also be used in cross-references and (type) expressions, -though nested symbols will be found even when omitted. -The ``@...`` name will always be rendered as **[anonymous]** (possibly as a -link). - -Example:: - - .. cpp:class:: Data - - .. cpp:union:: @data - - .. cpp:var:: int a - - .. cpp:var:: double b - - Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. - -This will be rendered as: - -.. cpp:class:: Data - :no-contents-entry: - :no-index-entry: - - .. cpp:union:: @data - :no-contents-entry: - :no-index-entry: - - .. cpp:var:: int a - :no-contents-entry: - :no-index-entry: - - .. cpp:var:: double b - :no-contents-entry: - :no-index-entry: - -Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. - -.. versionadded:: 1.8 - - -Aliasing Declarations -~~~~~~~~~~~~~~~~~~~~~ - -Sometimes it may be helpful list declarations elsewhere than their main -documentation, e.g., when creating a synopsis of a class interface. -The following directive can be used for this purpose. - -.. rst:directive:: .. cpp:alias:: name or function signature - - Insert one or more alias declarations. Each entity can be specified - as they can in the :rst:role:`cpp:any` role. - If the name of a function is given (as opposed to the complete signature), - then all overloads of the function will be listed. - - For example:: - - .. cpp:alias:: Data::a - overload_example::C::f - - becomes - - .. cpp:alias:: Data::a - overload_example::C::f - - whereas:: - - .. cpp:alias:: void overload_example::C::f(double d) const - void overload_example::C::f(double d) - - becomes - - .. cpp:alias:: void overload_example::C::f(double d) const - void overload_example::C::f(double d) - - .. versionadded:: 2.0 - - - .. rubric:: Options - - .. rst:directive:option:: maxdepth: int - - Insert nested declarations as well, up to the total depth given. - Use 0 for infinite depth and 1 for just the mentioned declaration. - Defaults to 1. - - .. versionadded:: 3.5 - - .. rst:directive:option:: noroot - - Skip the mentioned declarations and only render nested declarations. - Requires ``maxdepth`` either 0 or at least 2. - - .. versionadded:: 3.5 - - -Constrained Templates -~~~~~~~~~~~~~~~~~~~~~ - -.. warning:: The support for concepts is experimental. It is based on the - current draft standard and the Concepts Technical Specification. - The features may change as they evolve. - -.. note:: Sphinx does not currently support ``requires`` clauses. - -Placeholders -^^^^^^^^^^^^ - -Declarations may use the name of a concept to introduce constrained template -parameters, or the keyword ``auto`` to introduce unconstrained template -parameters:: - - .. cpp:function:: void f(auto &&arg) - - A function template with a single unconstrained template parameter. - - .. cpp:function:: void f(std::Iterator it) - - A function template with a single template parameter, constrained by the - Iterator concept. - -Template Introductions -^^^^^^^^^^^^^^^^^^^^^^ - -Simple constrained function or class templates can be declared with a `template -introduction` instead of a template parameter list:: - - .. cpp:function:: std::Iterator{It} void advance(It &it) - - A function template with a template parameter constrained to be an - Iterator. - - .. cpp:class:: std::LessThanComparable{T} MySortedContainer - - A class template with a template parameter constrained to be - LessThanComparable. - -They are rendered as follows. - -.. cpp:function:: std::Iterator{It} void advance(It &it) - :no-contents-entry: - :no-index-entry: - - A function template with a template parameter constrained to be an Iterator. - -.. cpp:class:: std::LessThanComparable{T} MySortedContainer - :no-contents-entry: - :no-index-entry: - - A class template with a template parameter constrained to be - LessThanComparable. - -Note however that no checking is performed with respect to parameter -compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction -even though it would not be valid C++. - -Inline Expressions and Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. rst:role:: cpp:expr - cpp:texpr - - Insert a C++ expression or type either as inline code (``cpp:expr``) - or inline text (``cpp:texpr``). For example:: - - .. cpp:var:: int a = 42 - - .. cpp:function:: int f(int i) - - An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). - - A type: :cpp:expr:`const MySortedContainer<int>&` - (or as text :cpp:texpr:`const MySortedContainer<int>&`). - - will be rendered as follows: - - .. cpp:var:: int a = 42 - :no-contents-entry: - :no-index-entry: - - .. cpp:function:: int f(int i) - :no-contents-entry: - :no-index-entry: - - An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). - - A type: :cpp:expr:`const MySortedContainer<int>&` - (or as text :cpp:texpr:`const MySortedContainer<int>&`). - - .. versionadded:: 1.7 - The :rst:role:`cpp:expr` role. - - .. versionadded:: 1.8 - The :rst:role:`cpp:texpr` role. - -Namespacing -~~~~~~~~~~~ - -Declarations in the C++ domain are as default placed in global scope. The -current scope can be changed using three namespace directives. They manage a -stack declarations where ``cpp:namespace`` resets the stack and changes a given -scope. - -The ``cpp:namespace-push`` directive changes the scope to a given inner scope -of the current one. - -The ``cpp:namespace-pop`` directive undoes the most recent -``cpp:namespace-push`` directive. - -.. rst:directive:: .. cpp:namespace:: scope specification - - Changes the current scope for the subsequent objects to the given scope, and - resets the namespace directive stack. Note that the namespace does not need - to correspond to C++ namespaces, but can end in names of classes, e.g.,:: - - .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass - - All subsequent objects will be defined as if their name were declared with - the scope prepended. The subsequent cross-references will be searched for - starting in the current scope. - - Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global - scope. - - A namespace declaration can also be templated, e.g.,:: - - .. cpp:class:: template<typename T> \ - std::vector - - .. cpp:namespace:: template<typename T> std::vector - - .. cpp:function:: std::size_t size() const - - declares ``size`` as a member function of the class template - ``std::vector``. Equivalently this could have been declared using:: - - .. cpp:class:: template<typename T> \ - std::vector - - .. cpp:function:: std::size_t size() const - - or:: - - .. cpp:class:: template<typename T> \ - std::vector - -.. rst:directive:: .. cpp:namespace-push:: scope specification - - Change the scope relatively to the current scope. For example, after:: - - .. cpp:namespace:: A::B - - .. cpp:namespace-push:: C::D - - the current scope will be ``A::B::C::D``. - - .. versionadded:: 1.4 - -.. rst:directive:: .. cpp:namespace-pop:: - - Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope). - For example, after:: - - .. cpp:namespace:: A::B - - .. cpp:namespace-push:: C::D - - .. cpp:namespace-pop:: - - the current scope will be ``A::B`` (*not* ``A::B::C``). - - If no previous ``cpp:namespace-push`` directive has been used, but only a - ``cpp:namespace`` directive, then the current scope will be reset to global - scope. That is, ``.. cpp:namespace:: A::B`` is equivalent to:: - - .. cpp:namespace:: nullptr - - .. cpp:namespace-push:: A::B - - .. versionadded:: 1.4 - -Info field lists -~~~~~~~~~~~~~~~~~ - -All the C++ directives for declaring entities support the following -info fields (see also :ref:`info-field-lists`): - -* ``tparam``: Description of a template parameter. - -The :rst:dir:`cpp:function` directive additionally supports the -following fields: - -* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter. -* ``returns``, ``return``: Description of a return value. -* ``retval``, ``retvals``: An alternative to ``returns`` for describing - the result of the function. -* `throws`, `throw`, `exception`: Description of a possibly thrown exception. - -.. versionadded:: 4.3 - The ``retval`` field type. - -.. _cpp-roles: - -Cross-referencing -~~~~~~~~~~~~~~~~~ - -These roles link to the given declaration types: - -.. rst:role:: cpp:any - cpp:class - cpp:struct - cpp:func - cpp:member - cpp:var - cpp:type - cpp:concept - cpp:enum - cpp:enumerator - - Reference a C++ declaration by name (see below for details). The name must - be properly qualified relative to the position of the link. - - .. versionadded:: 2.0 - The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class` - role. - -.. admonition:: Note on References with Templates Parameters/Arguments - - These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must - be taken when referencing a (partial) template specialization, e.g. if the - link looks like this: ``:cpp:class:`MyClass<int>```. - This is interpreted as a link to ``int`` with a title of ``MyClass``. - In this case, escape the opening angle bracket with a backslash, - like this: ``:cpp:class:`MyClass\<int>```. - - When a custom title is not needed it may be useful to use the roles for - inline expressions, :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where - angle brackets do not need escaping. - -Declarations without template parameters and template arguments -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For linking to non-templated declarations the name must be a nested name, e.g., -``f`` or ``MyClass::f``. - - -Overloaded (member) functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When a (member) function is referenced using just its name, the reference -will point to an arbitrary matching overload. -The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles use an alternative -format, which simply is a complete function declaration. -This will resolve to the exact matching overload. -As example, consider the following class declaration: - -.. cpp:namespace-push:: overload_example -.. cpp:class:: C - - .. cpp:function:: void f(double d) const - .. cpp:function:: void f(double d) - .. cpp:function:: void f(int i) - .. cpp:function:: void f() - -References using the :rst:role:`cpp:func` role: - -- Arbitrary overload: ``C::f``, :cpp:func:`C::f` -- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()` -- Specific overload: ``void C::f()``, :cpp:func:`void C::f()` -- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)` -- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)` -- Specific overload: ``void C::f(double) const``, - :cpp:func:`void C::f(double) const` - -Note that the :confval:`add_function_parentheses` configuration variable -does not influence specific overload references. - -.. cpp:namespace-pop:: - - -Templated declarations -^^^^^^^^^^^^^^^^^^^^^^ - -Assume the following declarations. - -.. cpp:class:: Wrapper - - .. cpp:class:: template<typename TOuter> \ - Outer - - .. cpp:class:: template<typename TInner> \ - Inner - -In general the reference must include the template parameter declarations, -and template arguments for the prefix of qualified names. For example: - -- ``template\<typename TOuter> Wrapper::Outer`` - (:cpp:class:`template\<typename TOuter> Wrapper::Outer`) -- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`` - (:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`) - -Currently the lookup only succeed if the template parameter identifiers are -equal strings. That is, ``template\<typename UOuter> Wrapper::Outer`` will not -work. - -As a shorthand notation, if a template parameter list is omitted, -then the lookup will assume either a primary template or a non-template, -but not a partial template specialisation. -This means the following references work as well: - -- ``Wrapper::Outer`` - (:cpp:class:`Wrapper::Outer`) -- ``Wrapper::Outer::Inner`` - (:cpp:class:`Wrapper::Outer::Inner`) -- ``template\<typename TInner> Wrapper::Outer::Inner`` - (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`) - -(Full) Template Specialisations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assume the following declarations. - -.. cpp:class:: template<typename TOuter> \ - Outer - - .. cpp:class:: template<typename TInner> \ - Inner - -.. cpp:class:: template<> \ - Outer<int> - - .. cpp:class:: template<typename TInner> \ - Inner - - .. cpp:class:: template<> \ - Inner<bool> - -In general the reference must include a template parameter list for each -template argument list. The full specialisation above can therefore be -referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<> -Outer\<int>`) and ``template\<> template\<> Outer\<int>::Inner\<bool>`` -(:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`). As a -shorthand the empty template parameter list can be omitted, e.g., -``Outer\<int>`` (:cpp:class:`Outer\<int>`) and ``Outer\<int>::Inner\<bool>`` -(:cpp:class:`Outer\<int>::Inner\<bool>`). - -Partial Template Specialisations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assume the following declaration. - -.. cpp:class:: template<typename T> \ - Outer<T*> - -References to partial specialisations must always include the template -parameter lists, e.g., ``template\<typename T> Outer\<T*>`` -(:cpp:class:`template\<typename T> Outer\<T*>`). Currently the lookup only -succeed if the template parameter identifiers are equal strings. - -Configuration Variables -~~~~~~~~~~~~~~~~~~~~~~~ - -See :ref:`cpp-config`. - -.. _domains-std: - -The Standard Domain +MOVED: Basic Markup ------------------- -The so-called "standard" domain collects all markup that doesn't warrant a -domain of its own. Its directives and roles are not prefixed with a domain -name. - -The standard domain is also where custom object descriptions, added using the -:func:`~sphinx.application.Sphinx.add_object_type` API, are placed. - -There is a set of directives allowing documenting command-line programs: - -.. rst:directive:: .. option:: name args, name args, ... - - Describes a command line argument or switch. Option argument names should - be enclosed in angle brackets. Examples:: - - .. option:: dest_dir - - Destination directory. - - .. option:: -m <module>, --module <module> - - Run a module as a script. - - The directive will create cross-reference targets for the given options, - referenceable by :rst:role:`option` (in the example case, you'd use something - like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```). - - .. versionchanged:: 5.3 - - One can cross-reference including an option value: ``:option:`--module=foobar```, - ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```. - - Use :confval:`option_emphasise_placeholders` for parsing of - "variable part" of a literal text (similarly to the :rst:role:`samp` role). - - ``cmdoption`` directive is a deprecated alias for the ``option`` directive. - -.. rst:directive:: .. envvar:: name - - Describes an environment variable that the documented code or program uses - or defines. Referenceable by :rst:role:`envvar`. - -.. rst:directive:: .. program:: name - - Like :rst:dir:`py:currentmodule`, this directive produces no output. - Instead, it serves to notify Sphinx that all following :rst:dir:`option` - directives document options for the program called *name*. - - If you use :rst:dir:`program`, you have to qualify the references in your - :rst:role:`option` roles by the program name, so if you have the following - situation :: - - .. program:: rm - - .. option:: -r - - Work recursively. - - .. program:: svn - - .. option:: -r <revision> - - Specify the revision to work upon. - - then ``:option:`rm -r``` would refer to the first option, while - ``:option:`svn -r``` would refer to the second one. - - If ``None`` is passed to the argument, the directive will reset the - current program name. - - The program name may contain spaces (in case you want to document - subcommands like ``svn add`` and ``svn commit`` separately). - - .. versionadded:: 0.5 - -There is also a very generic object description directive, which is not tied to -any domain: - -.. rst:directive:: .. describe:: text - .. object:: text - - This directive produces the same formatting as the specific ones provided by - domains, but does not create index entries or cross-referencing targets. - Example:: - - .. describe:: PAPER - - You can set this variable to select a paper size. - - -The JavaScript Domain ---------------------- - -The JavaScript domain (name **js**) provides the following directives: - -.. rst:directive:: .. js:module:: name - - This directive sets the module name for object declarations that follow - after. The module name is used in the global module index and in cross - references. This directive does not create an object heading like - :rst:dir:`py:class` would, for example. - - By default, this directive will create a linkable entity and will cause an - entry in the global module index, unless the ``no-index`` option is - specified. If this option is specified, the directive will only update the - current module name. - - .. versionadded:: 1.6 - .. versionchanged:: 5.2 - - Module directives support body content. - -.. rst:directive:: .. js:function:: name(signature) - - Describes a JavaScript function or method. If you want to describe - arguments as optional use square brackets as :ref:`documented <signatures>` - for Python signatures. - - You can use fields to give more details about arguments and their expected - types, errors which may be thrown by the function, and the value being - returned:: - - .. js:function:: $.getJSON(href, callback[, errback]) - - :param string href: An URI to the location of the resource. - :param callback: Gets called with the object. - :param errback: - Gets called in case the request fails. And a lot of other - text so we need multiple lines. - :throws SomeError: For whatever reason in that case. - :returns: Something. - - This is rendered as: - - .. js:function:: $.getJSON(href, callback[, errback]) - :no-index: - - :param string href: An URI to the location of the resource. - :param callback: Gets called with the object. - :param errback: - Gets called in case the request fails. And a lot of other - text so we need multiple lines. - :throws SomeError: For whatever reason in that case. - :returns: Something. - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's parameters will be emitted on a single logical - line, overriding :confval:`javascript_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. js:method:: name(signature) - - This directive is an alias for :rst:dir:`js:function`, however it describes - a function that is implemented as a method on a class object. - - .. versionadded:: 1.6 - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's parameters will be emitted on a single logical - line, overriding :confval:`javascript_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. js:class:: name - - Describes a constructor that creates an object. This is basically like a - function but will show up with a `class` prefix:: - - .. js:class:: MyAnimal(name[, age]) - - :param string name: The name of the animal - :param number age: an optional age for the animal - - This is rendered as: - - .. js:class:: MyAnimal(name[, age]) - :no-index: - - :param string name: The name of the animal - :param number age: an optional age for the animal - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's parameters will be emitted on a single logical - line, overriding :confval:`javascript_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. js:data:: name - - Describes a global variable or constant. - -.. rst:directive:: .. js:attribute:: object.name - - Describes the attribute *name* of *object*. - -.. _js-roles: - -These roles are provided to refer to the described objects: - -.. rst:role:: js:mod - js:func - js:meth - js:class - js:data - js:attr - - -The reStructuredText domain ---------------------------- - -The reStructuredText domain (name **rst**) provides the following directives: - -.. rst:directive:: .. rst:directive:: name - - Describes a reST directive. The *name* can be a single directive name or - actual directive syntax (`..` prefix and `::` suffix) with arguments that - will be rendered differently. For example:: - - .. rst:directive:: foo - - Foo description. - - .. rst:directive:: .. bar:: baz - - Bar description. - - will be rendered as: - - .. rst:directive:: foo - :no-index: - - Foo description. - - .. rst:directive:: .. bar:: baz - :no-index: - - Bar description. - -.. rst:directive:: .. rst:directive:option:: name - - Describes an option for reST directive. The *name* can be a single option - name or option name with arguments which separated with colon (``:``). - For example:: - - .. rst:directive:: toctree - - .. rst:directive:option:: caption: caption of ToC - - .. rst:directive:option:: glob - - will be rendered as: - - .. rst:directive:: toctree - :no-index: - - .. rst:directive:option:: caption: caption of ToC - :no-index: - - .. rst:directive:option:: glob - :no-index: - - .. rubric:: options - - .. rst:directive:option:: type: description of argument - :type: text - - Describe the type of option value. - - For example:: - - .. rst:directive:: toctree - - .. rst:directive:option:: maxdepth - :type: integer or no value - - .. versionadded:: 2.1 - -.. rst:directive:: .. rst:role:: name - - Describes a reST role. For example:: - - .. rst:role:: foo - - Foo description. - - will be rendered as: - - .. rst:role:: foo - :no-index: - - Foo description. - -.. _rst-roles: - -These roles are provided to refer to the described objects: - -.. rst:role:: rst:dir - rst:role - -.. _math-domain: - -The Math Domain +.. raw:: html + + <span id="basic-markup"> + <span id="basic-domain-markup"> + <span id="directive-default-domain"> + <span id="cross-referencing-syntax"> + +See :doc:`/usage/domains/index`. + + +MOVED: Python Domain +-------------------- + +.. raw:: html + + <span id="the-python-domain"> + <span id="python-domain"> + <span id="directive-py-module"> + <span id="directive-option-py-module-platform"> + <span id="directive-option-py-module-synopsis"> + <span id="directive-option-py-module-deprecated"> + <span id="directive-py-currentmodule"> + <span id="directive-py-function"> + <span id="directive-option-py-function-async"> + <span id="directive-option-py-function-canonical"> + <span id="directive-option-py-function-single-line-parameter-list"> + <span id="directive-option-py-function-single-line-type-parameter-list"> + <span id="directive-py-data"> + <span id="directive-option-py-data-type"> + <span id="directive-option-py-data-value"> + <span id="directive-option-py-data-canonical"> + <span id="directive-py-exception"> + <span id="index-0"> + <span id="directive-option-py-exception-final"> + <span id="directive-option-py-exception-single-line-parameter-list"> + <span id="directive-option-py-exception-single-line-type-parameter-list"> + <span id="directive-py-class"> + <span id="index-1"> + <span id="directive-option-py-class-canonical"> + <span id="directive-option-py-class-final"> + <span id="directive-option-py-class-single-line-parameter-list"> + <span id="directive-option-py-class-single-line-type-parameter-list"> + <span id="directive-py-attribute"> + <span id="directive-option-py-attribute-type"> + <span id="directive-option-py-attribute-value"> + <span id="directive-option-py-attribute-canonical"> + <span id="directive-py-property"> + <span id="directive-option-py-property-abstractmethod"> + <span id="directive-option-py-property-classmethod"> + <span id="directive-option-py-property-type"> + <span id="directive-py-method"> + <span id="directive-option-py-method-abstractmethod"> + <span id="directive-option-py-method-async"> + <span id="directive-option-py-method-canonical"> + <span id="directive-option-py-method-classmethod"> + <span id="directive-option-py-method-final"> + <span id="directive-option-py-method-single-line-parameter-list"> + <span id="directive-option-py-method-single-line-type-parameter-list"> + <span id="directive-option-py-method-staticmethod"> + <span id="directive-py-staticmethod"> + <span id="directive-py-classmethod"> + <span id="directive-py-decorator"> + <span id="directive-option-py-decorator-single-line-parameter-list"> + <span id="directive-option-py-decorator-single-line-type-parameter-list"> + <span id="directive-py-decoratormethod"> + <span id="python-signatures"> + <span id="signatures"> + <span id="index-2"> + <span id="index-3"> + <span id="info-field-lists"> + <span id="id1"> + <span id="cross-referencing-python-objects"> + <span id="python-roles"> + <span id="role-py-mod"> + <span id="role-py-func"> + <span id="role-py-data"> + <span id="role-py-const"> + <span id="role-py-class"> + <span id="role-py-meth"> + <span id="role-py-attr"> + <span id="role-py-exc"> + <span id="role-py-obj"> + +See :doc:`/usage/domains/python`. + + +MOVED: C Domain --------------- -The math domain (name **math**) provides the following roles: - -.. rst:role:: math:numref - - Role for cross-referencing equations defined by :rst:dir:`math` directive - via their label. Example:: - - .. math:: e^{i\pi} + 1 = 0 - :label: euler - - Euler's identity, equation :math:numref:`euler`, was elected one of the - most beautiful mathematical formulas. - - .. versionadded:: 1.8 +.. raw:: html + + <span id="the-c-domain"> + <span id="c-domain"> + <span id="directive-c-member"> + <span id="directive-c-var"> + <span id="directive-c-function"> + <span id="directive-option-c-function-single-line-parameter-list"> + <span id="directive-c-macro"> + <span id="directive-option-c-macro-single-line-parameter-list"> + <span id="directive-c-struct"> + <span id="directive-c-union"> + <span id="directive-c-enum"> + <span id="directive-c-enumerator"> + <span id="directive-c-type"> + <span id="cross-referencing-c-constructs"> + <span id="c-roles"> + <span id="role-c-member"> + <span id="role-c-data"> + <span id="role-c-var"> + <span id="role-c-func"> + <span id="role-c-macro"> + <span id="role-c-struct"> + <span id="role-c-union"> + <span id="role-c-enum"> + <span id="role-c-enumerator"> + <span id="role-c-type"> + <span id="anonymous-entities"> + <span id="aliasing-declarations"> + <span id="directive-c-alias"> + <span id="directive-option-c-alias-maxdepth"> + <span id="directive-option-c-alias-noroot"> + <span id="inline-expressions-and-types"> + <span id="role-c-expr"> + <span id="role-c-texpr"> + <span id="namespacing"> + <span id="directive-c-namespace"> + <span id="directive-c-namespace-push"> + <span id="directive-c-namespace-pop"> + <span id="configuration-variables"> + +See :doc:`/usage/domains/c`. + + +MOVED: C++ Domain +----------------- -More domains ------------- +.. raw:: html + + <span id="cpp-domain"> + <span id="id2"> + <span id="directives-for-declaring-entities"> + <span id="directive-cpp-class"> + <span id="directive-cpp-struct"> + <span id="directive-cpp-function"> + <span id="directive-option-cpp-function-single-line-parameter-list"> + <span id="directive-cpp-member"> + <span id="directive-cpp-var"> + <span id="directive-cpp-type"> + <span id="directive-cpp-enum"> + <span id="directive-cpp-enum-struct"> + <span id="directive-cpp-enum-class"> + <span id="directive-cpp-enumerator"> + <span id="directive-cpp-union"> + <span id="directive-cpp-concept"> + <span id="options"> + <span id="id3"> + <span id="id4"> + <span id="directive-cpp-alias"> + <span id="directive-option-cpp-alias-maxdepth"> + <span id="directive-option-cpp-alias-noroot"> + <span id="constrained-templates"> + <span id="placeholders"> + <span id="template-introductions"> + <span id="id5"> + <span id="role-cpp-expr"> + <span id="role-cpp-texpr"> + <span id="id6"> + <span id="directive-cpp-namespace"> + <span id="directive-cpp-namespace-push"> + <span id="directive-cpp-namespace-pop"> + <span id="id7"> + <span id="cross-referencing"> + <span id="cpp-roles"> + <span id="role-cpp-any"> + <span id="role-cpp-class"> + <span id="role-cpp-struct"> + <span id="role-cpp-func"> + <span id="role-cpp-member"> + <span id="role-cpp-var"> + <span id="role-cpp-type"> + <span id="role-cpp-concept"> + <span id="role-cpp-enum"> + <span id="role-cpp-enumerator"> + <span id="declarations-without-template-parameters-and-template-arguments"> + <span id="overloaded-member-functions"> + <span id="templated-declarations"> + <span id="full-template-specialisations"> + <span id="partial-template-specialisations"> + <span id="id8"> + +See :doc:`/usage/domains/cpp`. + + +MOVED: Standard Domain +---------------------- + +.. raw:: html + + <span id="the-standard-domain"> + <span id="domains-std"> + <span id="directive-option"> + <span id="directive-envvar"> + <span id="directive-program"> + <span id="directive-describe"> + <span id="directive-object"> + +See :doc:`/usage/domains/standard`. + + +MOVED: JavaScript Domain +------------------------ + +.. raw:: html + + <span id="the-javascript-domain"> + <span id="directive-js-module"> + <span id="directive-js-function"> + <span id="directive-option-js-function-single-line-parameter-list"> + <span id="directive-js-method"> + <span id="directive-option-js-method-single-line-parameter-list"> + <span id="directive-js-class"> + <span id="directive-option-js-class-single-line-parameter-list"> + <span id="directive-js-data"> + <span id="directive-js-attribute"> + <span id="js-roles"> + <span id="role-js-mod"> + <span id="role-js-func"> + <span id="role-js-meth"> + <span id="role-js-class"> + <span id="role-js-data"> + <span id="role-js-attr"> + +See :doc:`/usage/domains/javascript`. + + +MOVED: reStructuredText Domain +------------------------------ + +.. raw:: html + + <span id="the-restructuredtext-domain"> + <span id="directive-rst-directive"> + <span id="directive-rst-directive-option"> + <span id="directive-option-rst-directive-option-type"> + <span id="directive-rst-role"> + <span id="rst-roles"> + <span id="role-rst-dir"> + <span id="role-rst-role"> + +See :doc:`/usage/domains/restructuredtext`. + + +MOVED: Math Domain +------------------ + +.. raw:: html + + <span id="the-math-domain"> + <span id="math-domain"> + <span id="role-math-numref"> + +See :doc:`/usage/domains/mathematics`. + +MOVED: More domains +------------------- -The sphinx-contrib_ repository contains more domains available as extensions; -currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_ -domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_, -Jinja_, Operation_, and Scala_. +.. raw:: html -.. _sphinx-contrib: https://github.com/sphinx-contrib + <span id="more-domains"> -.. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/ -.. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/ -.. _CoffeeScript: https://pypi.org/project/sphinxcontrib-coffee/ -.. _Common Lisp: https://pypi.org/project/sphinxcontrib-cldomain/ -.. _dqn: https://pypi.org/project/sphinxcontrib-dqndomain/ -.. _Erlang: https://pypi.org/project/sphinxcontrib-erlangdomain/ -.. _Go: https://pypi.org/project/sphinxcontrib-golangdomain/ -.. _HTTP: https://pypi.org/project/sphinxcontrib-httpdomain/ -.. _Jinja: https://pypi.org/project/sphinxcontrib-jinjadomain/ -.. _Lasso: https://pypi.org/project/sphinxcontrib-lassodomain/ -.. _MATLAB: https://pypi.org/project/sphinxcontrib-matlabdomain/ -.. _Operation: https://pypi.org/project/sphinxcontrib-operationdomain/ -.. _PHP: https://pypi.org/project/sphinxcontrib-phpdomain/ -.. _Ruby: https://github.com/sphinx-contrib/rubydomain -.. _Scala: https://pypi.org/project/sphinxcontrib-scaladomain/ +See :doc:`/usage/domains/index`. diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst index 5fc897d..62dad5c 100644 --- a/doc/usage/restructuredtext/field-lists.rst +++ b/doc/usage/restructuredtext/field-lists.rst @@ -73,6 +73,6 @@ At the moment, these metadata fields are recognized: :nosearch: - .. note:: object search is still available even if `nosearch` option is set. + .. note:: object search is still available even if ``nosearch`` option is set. .. versionadded:: 3.0 diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst index 87b6ed6..0fe311e 100644 --- a/doc/usage/restructuredtext/index.rst +++ b/doc/usage/restructuredtext/index.rst @@ -21,4 +21,8 @@ __ https://docutils.sourceforge.io/rst.html roles directives field-lists + +.. toctree:: + :hidden: + domains diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index e468de9..b21a2b7 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -15,267 +15,28 @@ They are written as ``:rolename:`content```. :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find Python objects are very useful for this. -See :doc:`/usage/restructuredtext/domains` for roles added by domains. +See :doc:`/usage/domains/index` for roles added by domains. -.. _xref-syntax: - Cross-referencing syntax ------------------------ -Cross-references are generated by many semantic interpreted text roles. -Basically, you only need to write ``:role:`target```, and a link will be -created to the item named *target* of the type indicated by *role*. The link's -text will be the same as *target*. - -There are some additional facilities, however, that make cross-referencing -roles more versatile: - -* You may supply an explicit title and reference target, like in reST direct - hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link - text will be *title*. - -* If you prefix the content with ``!``, no reference/hyperlink will be created. - -* If you prefix the content with ``~``, the link text will only be the last - component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will - refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This - does not work with all cross-reference roles, but is domain specific. - - In HTML output, the link's ``title`` attribute (that is e.g. shown as a - tool-tip on mouse-hover) will always be the full target name. - - -.. _any-role: - -Cross-referencing anything -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. rst:role:: any - - .. versionadded:: 1.3 - - This convenience role tries to do its best to find a valid target for its - reference text. - - * First, it tries standard cross-reference targets that would be referenced - by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. - - Custom objects added to the standard domain by extensions (see - :meth:`.Sphinx.add_object_type`) are also searched. - - * Then, it looks for objects (targets) in all loaded domains. It is up to - the domains how specific a match must be. For example, in the Python - domain a reference of ``:any:`Builder``` would match the - ``sphinx.builders.Builder`` class. - - If none or multiple targets are found, a warning will be emitted. In the - case of multiple targets, you can change "any" to a specific role. - - This role is a good candidate for setting :confval:`default_role`. If you - do, you can write cross-references without a lot of markup overhead. For - example, in this Python function documentation:: - - .. function:: install() - - This function installs a `handler` for every signal known by the - `signal` module. See the section `about-signals` for more information. - - there could be references to a glossary term (usually ``:term:`handler```), a - Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a - section (usually ``:ref:`about-signals```). - - The :rst:role:`any` role also works together with the - :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is - found, all object types of intersphinx inventories are also searched. - -Cross-referencing objects -^^^^^^^^^^^^^^^^^^^^^^^^^ - -These roles are described with their respective domains: - -* :ref:`Python <python-roles>` -* :ref:`C <c-roles>` -* :ref:`C++ <cpp-roles>` -* :ref:`JavaScript <js-roles>` -* :ref:`ReST <rst-roles>` - - -.. _ref-role: - -Cross-referencing arbitrary locations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. rst:role:: ref - - To support cross-referencing to arbitrary locations in any document, the - standard reST labels are used. For this to work label names must be unique - throughout the entire documentation. There are two ways in which you can - refer to labels: - - * If you place a label directly before a section title, you can reference to - it with ``:ref:`label-name```. For example:: - - .. _my-reference-label: - - Section to cross-reference - -------------------------- - - This is the text of the section. - - It refers to the section itself, see :ref:`my-reference-label`. - - The ``:ref:`` role would then generate a link to the section, with the - link title being "Section to cross-reference". This works just as well - when section and reference are in different source files. - - Automatic labels also work with figures. For example:: - - .. _my-figure: - - .. figure:: whatever - - Figure caption - - In this case, a reference ``:ref:`my-figure``` would insert a reference - to the figure with link text "Figure caption". - - The same works for tables that are given an explicit caption using the - :dudir:`table` directive. - - * Labels that aren't placed before a section title can still be referenced, - but you must give the link an explicit title, using this syntax: - ``:ref:`Link title <label-name>```. - - .. note:: +See :doc:`/usage/referencing/`. - Reference labels must start with an underscore. When referencing a label, - the underscore must be omitted (see examples above). +Cross-reference roles include: - Using :rst:role:`ref` is advised over standard reStructuredText links to - sections (like ```Section title`_``) because it works across files, when - section headings are changed, will raise warnings if incorrect, and works - for all builders that support cross-references. +* :rst:role:`any` +* :rst:role:`doc` +* :rst:role:`download` +* :rst:role:`envvar` +* :rst:role:`keyword` +* :rst:role:`numref` +* :rst:role:`option` (and the deprecated :rst:role:`!cmdoption`) +* :rst:role:`ref` +* :rst:role:`term` +* :rst:role:`token` -Cross-referencing documents -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 0.6 - -There is also a way to directly link to documents: - -.. rst:role:: doc - - Link to the specified document; the document name can be specified in - absolute or relative fashion. For example, if the reference - ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link - refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or - ``:doc:`../people```, the link refers to ``people``. - - If no explicit link text is given (like usual: ``:doc:`Monty Python members - </people>```), the link caption will be the title of the given document. - - -Referencing downloadable files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 0.6 - -.. rst:role:: download - - This role lets you link to files within your source tree that are not reST - documents that can be viewed, but files that can be downloaded. - - When you use this role, the referenced file is automatically marked for - inclusion in the output when building (obviously, for HTML output only). - All downloadable files are put into a ``_downloads/<unique hash>/`` - subdirectory of the output directory; duplicate filenames are handled. - - An example:: - - See :download:`this example script <../example.py>`. - - The given filename is usually relative to the directory the current source - file is contained in, but if it absolute (starting with ``/``), it is taken - as relative to the top source directory. - - The ``example.py`` file will be copied to the output directory, and a - suitable link generated to it. - - Not to show unavailable download links, you should wrap whole paragraphs that - have this role:: - - .. only:: builder_html - - See :download:`this example script <../example.py>`. - -Cross-referencing figures by figure number -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 1.3 - -.. versionchanged:: 1.5 - `numref` role can also refer sections. - And `numref` allows `{name}` for the link text. - -.. rst:role:: numref - - Link to the specified figures, tables, code-blocks and sections; the standard - reST labels are used. When you use this role, it will insert a reference to - the figure with link text by its figure number like "Fig. 1.1". - - If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig. - %s) <my-figure>```), the link caption will serve as title of the reference. - As placeholders, `%s` and `{number}` get replaced by the figure - number and `{name}` by the figure caption. - If no explicit link text is given, the :confval:`numfig_format` setting is - used as fall-back default. - - If :confval:`numfig` is ``False``, figures are not numbered, - so this role inserts not a reference but the label or the link text. - -Cross-referencing other items of interest -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following roles do possibly create a cross-reference, but do not refer to -objects: - -.. rst:role:: envvar - - An environment variable. Index entries are generated. Also generates a link - to the matching :rst:dir:`envvar` directive, if it exists. - -.. rst:role:: token - - The name of a grammar token (used to create links between - :rst:dir:`productionlist` directives). - -.. rst:role:: keyword - - The name of a keyword in Python. This creates a link to a reference label - with that name, if it exists. - -.. rst:role:: option - - A command-line option to an executable program. This generates a link to - a :rst:dir:`option` directive, if it exists. - - -The following role creates a cross-reference to a term in a -:ref:`glossary <glossary-directive>`: - -.. rst:role:: term - - Reference to a term in a glossary. A glossary is created using the - ``glossary`` directive containing a definition list with terms and - definitions. It does not have to be in the same file as the ``term`` markup, - for example the Python docs have one global glossary in the ``glossary.rst`` - file. - - If you use a term that's not explained in a glossary, you'll get a warning - during build. - Inline code highlighting ------------------------ @@ -414,6 +175,10 @@ different style: ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an external site rendering the manpage if :confval:`manpages_url` is defined. + .. versionchanged:: 7.3 + Allow specifying a target with ``<>``, like hyperlinks. + For example, ``:manpage:`blah <ls(1)>``` displays :manpage:`blah <ls(1)>`. + .. rst:role:: menuselection Menu selections should be marked using the ``menuselection`` role. This is @@ -468,14 +233,17 @@ different style: A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a "variable" part, as in :rst:role:`file`. For - example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be - emphasized: :samp:`print 1+{variable}` + example, in ``:samp:`print(1+{variable})```, the part ``variable`` would be + emphasized: :samp:`print(1+{variable})` If you don't need the "variable part" indication, use the standard :rst:role:`code` role instead. .. versionchanged:: 1.8 - Allowed to escape curly braces with backslash + Allowed to escape curly braces with double backslash. For example, in + ``:samp:`print(f"answer=\\{1+{variable}*2\\}")```, the part ``variable`` + would be emphasized and the escaped curly braces would be displayed: + :samp:`print(f"answer=\\{1+{variable}*2\\}")` There is also an :rst:role:`index` role to generate index entries. @@ -508,7 +276,7 @@ the standard reST markup for that purpose. Substitutions ------------- -The documentation system provides three substitutions that are defined by +The documentation system provides some substitutions that are defined by default. They are set in the build configuration file. .. describe:: |release| @@ -532,5 +300,5 @@ default. They are set in the build configuration file. .. describe:: |translation progress| Replaced by the translation progress of the document. - This substitution is intented for use by document translators + This substitution is intended for use by document translators as a marker for the translation progress of the document. |