diff options
Diffstat (limited to 'doc/usage/domains')
| -rw-r--r-- | doc/usage/domains/c.rst | 4 | ||||
| -rw-r--r-- | doc/usage/domains/cpp.rst | 2 | ||||
| -rw-r--r-- | doc/usage/domains/index.rst | 4 | ||||
| -rw-r--r-- | doc/usage/domains/javascript.rst | 2 | ||||
| -rw-r--r-- | doc/usage/domains/python.rst | 68 | ||||
| -rw-r--r-- | doc/usage/domains/restructuredtext.rst | 13 | ||||
| -rw-r--r-- | doc/usage/domains/standard.rst | 38 |
7 files changed, 114 insertions, 17 deletions
diff --git a/doc/usage/domains/c.rst b/doc/usage/domains/c.rst index 3c1a41d..49aa5ca 100644 --- a/doc/usage/domains/c.rst +++ b/doc/usage/domains/c.rst @@ -24,7 +24,7 @@ The C domain (name **c**) is suited for documentation of C API. .. 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. + it is not parsed by the reStructuredText inliner. In the description of a function you can use the following info fields (see also :ref:`info-field-lists`). @@ -128,7 +128,7 @@ The C domain (name **c**) is suited for documentation of C API. Describes a C type, either as a typedef, or the alias for an unspecified type. -.. _c-roles: +.. _c-xref-roles: Cross-referencing C constructs ------------------------------ diff --git a/doc/usage/domains/cpp.rst b/doc/usage/domains/cpp.rst index 6c9372b..57cb932 100644 --- a/doc/usage/domains/cpp.rst +++ b/doc/usage/domains/cpp.rst @@ -568,7 +568,7 @@ following fields: .. versionadded:: 4.3 The ``retval`` field type. -.. _cpp-roles: +.. _cpp-xref-roles: Cross-referencing ----------------- diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst index b5d43ce..8c47134 100644 --- a/doc/usage/domains/index.rst +++ b/doc/usage/domains/index.rst @@ -1,5 +1,7 @@ .. highlight:: rst +.. _usage-domains: + ======= Domains ======= @@ -121,7 +123,7 @@ This is particularly useful for literate programming: .. py:function:: spam(eggs) :no-typesetting: - .. code:: + .. code:: python def spam(eggs): pass diff --git a/doc/usage/domains/javascript.rst b/doc/usage/domains/javascript.rst index 630b52e..ba0ff10 100644 --- a/doc/usage/domains/javascript.rst +++ b/doc/usage/domains/javascript.rst @@ -120,7 +120,7 @@ The JavaScript domain (name **js**) provides the following directives: Describes the attribute *name* of *object*. -.. _js-roles: +.. _js-xref-roles: These roles are provided to refer to the described objects: diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst index 96982f1..5b98baa 100644 --- a/doc/usage/domains/python.rst +++ b/doc/usage/domains/python.rst @@ -124,8 +124,9 @@ The following directives are provided for module and class contents: .. 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. + as "defined constants." + Consider using :rst:dir:`py:type` for type aliases instead + and :rst:dir:`py:attribute` for class variables and instance attributes. .. rubric:: options @@ -259,6 +260,7 @@ The following directives are provided for module and class contents: 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. + Type aliases should be documented with :rst:dir:`py:type`. .. rubric:: options @@ -315,6 +317,55 @@ The following directives are provided for module and class contents: Describe the location where the object is defined. The default value is the module specified by :rst:dir:`py:currentmodule`. +.. rst:directive:: .. py:type:: name + + Describe a :ref:`type alias <python:type-aliases>`. + + The type that the alias represents should be described + with the :rst:dir:`!canonical` option. + This directive supports an optional description body. + + For example: + + .. code-block:: rst + + .. py:type:: UInt64 + + Represent a 64-bit positive integer. + + will be rendered as follows: + + .. py:type:: UInt64 + :no-contents-entry: + :no-index-entry: + + Represent a 64-bit positive integer. + + .. rubric:: options + + .. rst:directive:option:: canonical + :type: text + + The canonical type represented by this alias, for example: + + .. code-block:: rst + + .. py:type:: StrPattern + :canonical: str | re.Pattern[str] + + Represent a regular expression or a compiled pattern. + + This is rendered as: + + .. py:type:: StrPattern + :no-contents-entry: + :no-index-entry: + :canonical: str | re.Pattern[str] + + Represent a regular expression or a compiled pattern. + + .. versionadded:: 7.4 + .. rst:directive:: .. py:method:: name(parameters) .. py:method:: name[type parameters](parameters) @@ -494,7 +545,7 @@ 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 +.. code-block:: python class AnimalList[AnimalT](list[AnimalT]): ... @@ -504,7 +555,7 @@ declared directly within the class or function definition: The corresponding reStructuredText documentation would be: -.. code:: rst +.. code-block:: rst .. py:class:: AnimalList[AnimalT] @@ -522,7 +573,8 @@ Info field lists meta fields are added. -Inside Python object description directives, reST field lists with these fields +Inside Python object description directives, +reStructuredText field lists with these fields are recognized and formatted nicely: * ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``: @@ -604,7 +656,7 @@ word "or":: :vartype a_var: str or int :rtype: float or str -.. _python-roles: +.. _python-xref-roles: Cross-referencing Python objects -------------------------------- @@ -649,6 +701,10 @@ a matching identifier is found: .. note:: The role is also able to refer to property. +.. rst:role:: py:type + + Reference a type alias. + .. rst:role:: py:exc Reference an exception. A dotted name may be used. diff --git a/doc/usage/domains/restructuredtext.rst b/doc/usage/domains/restructuredtext.rst index 3a936a6..639b686 100644 --- a/doc/usage/domains/restructuredtext.rst +++ b/doc/usage/domains/restructuredtext.rst @@ -10,9 +10,10 @@ 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:: + Describes a reStructuredText 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 @@ -38,7 +39,7 @@ The reStructuredText domain (name **rst**) provides the following directives: .. rst:directive:: .. rst:directive:option:: name - Describes an option for reST directive. The *name* can be a single option + Describes an option for reStructuredText directive. The *name* can be a single option name or option name with arguments which separated with colon (``:``). For example:: @@ -77,7 +78,7 @@ The reStructuredText domain (name **rst**) provides the following directives: .. rst:directive:: .. rst:role:: name - Describes a reST role. For example:: + Describes a reStructuredText role. For example:: .. rst:role:: foo @@ -91,7 +92,7 @@ The reStructuredText domain (name **rst**) provides the following directives: Foo description. -.. _rst-roles: +.. _rst-xref-roles: These roles are provided to refer to the described objects: diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst index 59b7e72..a676a2d 100644 --- a/doc/usage/domains/standard.rst +++ b/doc/usage/domains/standard.rst @@ -42,6 +42,44 @@ There is a set of directives allowing documenting command-line programs: ``cmdoption`` directive is a deprecated alias for the ``option`` directive. +.. rst:directive:: .. confval:: name + + Describes a configuration value or setting that the documented + code or program uses or defines. + Referenceable by :rst:role:`confval`. + + .. rst:directive:option:: type + :type: text + + Describes the type of the configuration value. + This is optional, and if specified will be interpreted as reStructuredText. + + .. rst:directive:option:: default + :type: text + + Describes the default value of the configuration value. + This is optional, and if specified will be interpreted as reStructuredText. + + Example: + + .. code-block:: rst + + .. confval:: the_answer + :type: ``int`` (a *number*) + :default: **42** + + This is a setting that controls the value of the answer. + + will be rendered as follows: + + .. confval:: the_answer + :no-contents-entry: + :no-index-entry: + :type: ``int`` (a *number*) + :default: **42** + + This is a setting that controls the value of the answer. + .. rst:directive:: .. envvar:: name Describes an environment variable that the documented code or program uses |