summaryrefslogtreecommitdiffstats
path: root/doc/usage/restructuredtext
diff options
context:
space:
mode:
Diffstat (limited to 'doc/usage/restructuredtext')
-rw-r--r--doc/usage/restructuredtext/basics.rst2
-rw-r--r--doc/usage/restructuredtext/directives.rst28
-rw-r--r--doc/usage/restructuredtext/domains.rst2563
-rw-r--r--doc/usage/restructuredtext/field-lists.rst2
-rw-r--r--doc/usage/restructuredtext/index.rst4
-rw-r--r--doc/usage/restructuredtext/roles.rst282
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.