Overhaul py directive documentation, remove old practices.

This commit is contained in:
Georg Brandl 2014-01-13 19:12:42 +01:00
parent 9708319f5c
commit 78b5d9aac2

View File

@ -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
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~