47
Sphinx Documentation, Release 1.4.1
.. py:module:: name
This directive marks the beginning of the description of a module (or package submodule, in which
case the name should be fully qualified, including thepackage name). It does not create content (like
e.g.py:class does).
This directive will alsocause an entry in the global module index.
The platform option, if present, is a comma-separated list of the platforms on which the module
is available (if it is available on all platforms, the option should be omitted). The keys are short
identifiers; examples that are in use include “IRIX”, “Mac”, “Windows”, and “Unix”. It is important
tousea key which has already been used when applicable.
Thesynopsis option should consistof onesentencedescribingthemodule’spurpose–itiscurrently
only used in the Global Module Index.
The deprecated option can be given (with no value) to mark a module as deprecated; it will be
designated as such in various locations then.
.. py:currentmodule:: name
This directive tells Sphinx that the classes, functions etc. documented from here are in the given
module (likepy:module), but it will not create index entries, an entry in the Global Module Index,
or a link target forpy:mod. This is helpful in situations where documentation for things in a module
is spread over multiple files or sections – one location has thepy:module directive, the others only
py:currentmodule.
The following directives areprovided for module and class contents:
.. py:function:: name(parameters)
Describes a module-level function. The signature should include the parameters as given in the
Python function definition,seePythonSignatures. Forexample:
.. py:function:: Timer.repeat(repeat=3, number=1000000)
Formethods you should usepy:method.
The description normally includesinformationaboutthe parameters required and how they are used
(especially whether mutable objects passed as parameters are modified), side effects, and possible
exceptions.
This information can (in anypy directive) optionally be given in a structured form, seeInfofieldlists.
.. 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.
.. py:exception:: name
Describes an exception class. The signature can, but need not include parentheses with constructor
arguments.
.. py:class:: name
.. py:class:: name(parameters)
Describes a class. The signature can optionally include parentheses with parameters which will be
shown as theconstructorarguments. See alsoPythonSignatures.
Methods and attributes belonging to the class should be placed in this directive’s body. If they are
placed outside, the supplied name should contain the class name so that cross-references still work.
Example:
.. py:class:: Foo
.. py:method:: quux()
8.3. The Python Domain
49