Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Disambiguate :type: as a directive option or field-list item #13242

Merged
merged 1 commit into from
Jan 15, 2025
Merged

Disambiguate :type: as a directive option or field-list item #13242

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 31 additions & 3 deletions doc/usage/domains/python.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,14 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the variable
:type: text

This will be parsed as a Python expression for cross-referencing
the type annotation.
As such, the argument to ``:type:`` should be a valid Python expression.

.. caution:: The valid syntax for the ``:type:`` directive option
differs from the syntax for the ``:type:`` `info field
<info-field-lists_>`__.

.. versionadded:: 2.4

.. rst:directive:option:: value: initial value of the variable
Expand Down Expand Up @@ -267,6 +275,14 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the attribute
:type: text

This will be parsed as a Python expression for cross-referencing
the type annotation.
As such, the argument to ``:type:`` should be a valid Python expression.

.. caution:: The valid syntax for the ``:type:`` directive option
differs from the syntax for the ``:type:`` `info field
<info-field-lists_>`__.

.. versionadded:: 2.4

.. rst:directive:option:: value: initial value of the attribute
Expand Down Expand Up @@ -311,6 +327,14 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the property
:type: text

This will be parsed as a Python expression for cross-referencing
the type annotation.
As such, the argument to ``:type:`` should be a valid Python expression.

.. caution:: The valid syntax for the ``:type:`` directive option
differs from the syntax for the ``:type:`` `info field
<info-field-lists_>`__.

.. rst::directive:option:: module
:type: text

Expand Down Expand Up @@ -608,7 +632,7 @@ explained by an example::
: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
:type priority: int or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
Expand Down Expand Up @@ -649,13 +673,17 @@ using the following syntax::
: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"::
Multiple types in a type field will be linked automatically
if separated by either the vertical bar (``|``) or the word "or"::

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str

:type an_arg: int | None
:vartype a_var: str | int
:rtype: float | str

.. _python-xref-roles:

Cross-referencing Python objects
Expand Down
Loading