IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Disambiguate `:type:` as a directive option or info-field-list item (#13242)

Browse Source
This commit is contained in:
Adam Turner 2025-01-15 00:20:42 +00:00 committed by GitHub
parent 2431c665d6
commit 182c831c7d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 31 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/usage/domains/python.rst
View File

@ -133,6 +133,14 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the variable .. rst:directive:option:: type: type of the variable
:type: text :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 .. versionadded:: 2.4
.. rst:directive:option:: value: initial value of the variable .. rst:directive:option:: value: initial value of the variable
@ -267,6 +275,14 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the attribute .. rst:directive:option:: type: type of the attribute
:type: text :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 .. versionadded:: 2.4
.. rst:directive:option:: value: initial value of the attribute .. rst:directive:option:: value: initial value of the attribute
@ -311,6 +327,14 @@ The following directives are provided for module and class contents:
.. rst:directive:option:: type: type of the property .. rst:directive:option:: type: type of the property
:type: text :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 .. rst::directive:option:: module
:type: text :type: text
@ -608,7 +632,7 @@ explained by an example::
:param str recipient: The recipient of the message :param str recipient: The recipient of the message
:param str message_body: The body 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 :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 :return: the message id
:rtype: int :rtype: int
:raises ValueError: if the message_body exceeds 160 characters :raises ValueError: if the message_body exceeds 160 characters
@ -649,13 +673,17 @@ using the following syntax::
:type point: tuple(float, float) :type point: tuple(float, float)
:type point: tuple[float, float] :type point: tuple[float, float]
Multiple types in a type field will be linked automatically if separated by the Multiple types in a type field will be linked automatically
word "or":: if separated by either the vertical bar (``|``) or the word "or"::
:type an_arg: int or None :type an_arg: int or None
:vartype a_var: str or int :vartype a_var: str or int
:rtype: float or str :rtype: float or str
:type an_arg: int | None
:vartype a_var: str | int
:rtype: float | str
.. _python-xref-roles: .. _python-xref-roles:
Cross-referencing Python objects Cross-referencing Python objects