mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Overhaul py directive documentation, remove old practices.
This commit is contained in:
parent
9708319f5c
commit
78b5d9aac2
@ -171,20 +171,18 @@ The following directives are provided for module and class contents:
|
|||||||
.. rst:directive:: .. py:function:: name(parameters)
|
.. rst:directive:: .. py:function:: name(parameters)
|
||||||
|
|
||||||
Describes a module-level function. The signature should include the
|
Describes a module-level function. The signature should include the
|
||||||
parameters, enclosing optional parameters in brackets. Default values can be
|
parameters as given in the Python function definition, see :ref:`signatures`.
|
||||||
given if it enhances clarity; see :ref:`signatures`. For example::
|
For example::
|
||||||
|
|
||||||
.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
|
.. py:function:: Timer.repeat(repeat=3, number=1000000)
|
||||||
|
|
||||||
Object methods are not documented using this directive. Bound object methods
|
For methods you should use :rst:dir:`py:method`.
|
||||||
placed in the module namespace as part of the public interface of the module
|
|
||||||
are documented using this, as they are equivalent to normal functions for
|
|
||||||
most purposes.
|
|
||||||
|
|
||||||
The description should include information about the parameters required and
|
The description should include information about the parameters required and
|
||||||
how they are used (especially whether mutable objects passed as parameters
|
how they are used (especially whether mutable objects passed as parameters
|
||||||
are modified), side effects, and possible exceptions. A small example may be
|
are modified), side effects, and possible exceptions. This information can
|
||||||
provided.
|
optionally be given in a structured form, see :ref:`info-field-lists`. A
|
||||||
|
small example may be provided.
|
||||||
|
|
||||||
.. rst:directive:: .. py:class:: name
|
.. rst:directive:: .. py:class:: name
|
||||||
.. py:class:: name(parameters)
|
.. py:class:: name(parameters)
|
||||||
@ -198,6 +196,7 @@ The following directives are provided for module and class contents:
|
|||||||
contain the class name so that cross-references still work. Example::
|
contain the class name so that cross-references still work. Example::
|
||||||
|
|
||||||
.. py:class:: Foo
|
.. py:class:: Foo
|
||||||
|
|
||||||
.. py:method:: quux()
|
.. py:method:: quux()
|
||||||
|
|
||||||
-- or --
|
-- or --
|
||||||
@ -218,7 +217,8 @@ The following directives are provided for module and class contents:
|
|||||||
|
|
||||||
Describes an object method. The parameters should not include the ``self``
|
Describes an object method. The parameters should not include the ``self``
|
||||||
parameter. The description should include similar information to that
|
parameter. The description should include similar information to that
|
||||||
described for ``function``. See also :ref:`signatures`.
|
described for ``function``. See also :ref:`signatures` and
|
||||||
|
:ref:`info-field-lists`.
|
||||||
|
|
||||||
.. rst:directive:: .. py:staticmethod:: name(parameters)
|
.. rst:directive:: .. py:staticmethod:: name(parameters)
|
||||||
|
|
||||||
@ -235,9 +235,8 @@ The following directives are provided for module and class contents:
|
|||||||
.. rst:directive:: .. py:decorator:: name
|
.. rst:directive:: .. py:decorator:: name
|
||||||
.. py:decorator:: name(parameters)
|
.. py:decorator:: name(parameters)
|
||||||
|
|
||||||
Describes a decorator function. The signature should *not* represent the
|
Describes a decorator function. The signature should represent the usage as
|
||||||
signature of the actual function, but the usage as a decorator. For example,
|
a decorator. For example, given the functions
|
||||||
given the functions
|
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
@ -280,23 +279,24 @@ Python Signatures
|
|||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Signatures of functions, methods and class constructors can be given like they
|
Signatures of functions, methods and class constructors can be given like they
|
||||||
would be written in Python, with the exception that optional parameters can be
|
would be written in Python.
|
||||||
indicated by brackets::
|
|
||||||
|
|
||||||
.. py:function:: compile(source[, filename[, symbol]])
|
|
||||||
|
|
||||||
It is customary to put the opening bracket before the comma. In addition to
|
|
||||||
this "nested" bracket style, a "flat" style can also be used, due to the fact
|
|
||||||
that most optional parameters can be given independently::
|
|
||||||
|
|
||||||
.. py:function:: compile(source[, filename, symbol])
|
|
||||||
|
|
||||||
Default values for optional arguments can be given (but if they contain commas,
|
Default values for optional arguments can be given (but if they contain commas,
|
||||||
they will confuse the signature parser). Python 3-style argument annotations
|
they will confuse the signature parser). Python 3-style argument annotations
|
||||||
can also be given as well as return type annotations::
|
can also be given as well as return type annotations::
|
||||||
|
|
||||||
.. py:function:: compile(source : string[, filename, symbol]) -> ast object
|
.. 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]])
|
||||||
|
|
||||||
|
It is customary to put the opening bracket before the comma.
|
||||||
|
|
||||||
|
|
||||||
|
.. _info-field-lists:
|
||||||
|
|
||||||
Info field lists
|
Info field lists
|
||||||
~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~
|
||||||
|
Loading…
Reference in New Issue
Block a user