| 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 to use a key which has already been used when applicable. |
| |
| The ``synopsis`` option should consist of one sentence describing the |
| module's purpose -- it is currently only used in the Global Module Index. |
| |
n | 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. |
| |
| .. describe:: moduleauthor |
| |
| The ``moduleauthor`` directive, which can appear multiple times, names the |
| authors of the module code, just like ``sectionauthor`` names the author(s) |
| of a piece of documentation. It too does not result in any output currently. |
n | |
| |
| .. note:: |
| |
| It is important to make the section title of a module-describing file |
| meaningful since that value will be inserted in the table-of-contents trees |
| in overview files. |
| |
| |
| * The highlighting language can be changed using the ``highlightlang`` |
| directive, used as follows:: |
| |
| .. highlightlang:: c |
| |
| This language is used until the next ``highlightlang`` directive is |
| encountered. |
| |
n | * The valid values for the highlighting language are: |
n | * The values normally used for the highlighting language are: |
| |
| * ``python`` (the default) |
| * ``c`` |
| * ``rest`` |
| * ``none`` (no highlighting) |
| |
| * If highlighting with the current language fails, the block is not highlighted |
| in any way. |
| |
| Longer displays of verbatim text may be included by storing the example text in |
| an external file containing only plain text. The file may be included using the |
n | standard ``include`` directive with the ``literal`` option flag. For example, |
n | ``literalinclude`` directive. [1]_ For example, to include the Python source file |
| to include the Python source file :file:`example.py`, use:: |
| :file:`example.py`, use:: |
| |
n | .. include:: example.py |
n | .. literalinclude:: example.py |
| :literal: |
| |
| The file name is relative to the current file's path. Documentation-specific |
| include files should be placed in the ``Doc/includes`` subdirectory. |
| |
| |
| Inline markup |
| ------------- |
| |
| As said before, Sphinx uses interpreted text roles to insert semantic markup in |
| documents. |
| |
n | The default role is ``var``, as that was one of the most common macros used in |
n | Names of local variables, such as function/method arguments, are an exception, |
| the old LaTeX docs. That means that you can use ```var``` to refer to a |
| they should be marked simply with ``*var*``. |
| variable named "var". |
| |
| For all other roles, you have to write ``:rolename:`content```. |
n | |
| There are some additional facilities that make cross-referencing roles more |
| versatile: |
| |
| * You may supply an explicit title and reference target, like in reST direct |
| hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link |
| text will be *title*. |
| |
| * If you prefix the content with ``!``, no reference/hyperlink will be created. |
| |
| * For the Python object roles, if you prefix the content with ``~``, the link |
| text will only be the last component of the target. For example, |
| ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only |
| display ``get`` as the link text. |
| |
| In HTML output, the link's ``title`` attribute (that is e.g. shown as a |
| tool-tip on mouse-hover) will always be the full target name. |
| |
| The following roles refer to objects in modules and are possibly hyperlinked if |
| a matching identifier is found: |
| |
| .. describe:: mod |
| |
| The name of a module; a dotted name may be used. This should also be used for |
| package names. |
| |
| .. describe:: func |
| |
| The name of a Python function; dotted names may be used. The role text |
n | should include trailing parentheses to enhance readability. The parentheses |
n | should not include trailing parentheses to enhance readability. The |
| are stripped when searching for identifiers. |
| parentheses are stripped when searching for identifiers. |
| |
| .. describe:: data |
| |
n | The name of a module-level variable. |
n | The name of a module-level variable or constant. |
| |
| .. describe:: const |
| |
| The name of a "defined" constant. This may be a C-language ``#define`` |
| or a Python variable that is not intended to be changed. |
| |
| .. describe:: class |
| |
| A class name; a dotted name may be used. |
| |
| .. describe:: meth |
| |
| The name of a method of an object. The role text should include the type |
n | name, method name and the trailing parentheses. A dotted name may be used. |
n | name and the method name. A dotted name may be used. |
| |
| .. describe:: attr |
| |
| The name of a data attribute of an object. |
| |
| .. describe:: exc |
| |
| The name of an exception. A dotted name may be used. |
| |
| The name enclosed in this markup can include a module name and/or a class name. |
| For example, ``:func:`filter``` could refer to a function named ``filter`` in |
| the current module, or the built-in function of that name. In contrast, |
| ``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` |
| module. |
| |
n | Normally, names in these roles are searched first without any further |
| qualification, then with the current module name prepended, then with the |
| current module and class name (if any) prepended. If you prefix the name with a |
| dot, this order is reversed. For example, in the documentation of the |
| :mod:`codecs` module, ``:func:`open``` always refers to the built-in function, |
| while ``:func:`.open``` refers to :func:`codecs.open`. |
| |
| A similar heuristic is used to determine whether the name is an attribute of |
| the currently documented class. |
| |
| The following roles create cross-references to C-language constructs if they |
| are defined in the API documentation: |
| |
| .. describe:: cdata |
| |
| mainly contained in information units, such as the language reference. |
| |
| The directive is ``index`` and contains one or more index entries. Each entry |
| consists of a type and a value, separated by a colon. |
| |
| For example:: |
| |
| .. index:: |
n | single: execution!context |
n | single: execution; context |
| module: __main__ |
| module: sys |
| triple: module; search; path |
| |
| This directive contains five entries, which will be converted to entries in the |
| generated index which link to the exact location of the index statement (or, in |
| case of offline media, the corresponding page number). |
| |
| The possible entry types are: |
| |
| single |
| Creates a single index entry. Can be made a subentry by separating the |
n | subentry text with a semicolon (this is also used below to describe what |
n | subentry text with a semicolon (this notation is also used below to describe |
| entries are created). |
| what entries are created). |
| pair |
| ``pair: loop; statement`` is a shortcut that creates two index entries, |
| namely ``loop; statement`` and ``statement; loop``. |
| triple |
| Likewise, ``triple: module; search; path`` is a shortcut that creates three |
| index entries, which are ``module; search path``, ``search; path, module`` and |
n | ``path; module search``. |
n | ``path; module search``. |
| module, keyword, operator, object, exception, statement, builtin |
| These all create two index entries. For example, ``module: hashlib`` creates |
| the entries ``module; hashlib`` and ``hashlib; module``. |
n | |
| For index directives containing only "single" entries, there is a shorthand |
| notation:: |
| |
| .. index:: BNF, grammar, syntax, notation |
| |
| This creates four index entries. |
| |
| |
| Grammar production displays |
| --------------------------- |
| |
| Special markup is available for displaying the productions of a formal grammar. |
| The markup is simple and does not attempt to model all aspects of BNF (or any |
| derived forms), but provides enough to allow context-free grammars to be |
| given on a single line and consists of a name, separated by a colon from the |
| following definition. If the definition spans multiple lines, each |
| continuation line must begin with a colon placed at the same column as in the |
| first line. |
| |
| Blank lines are not allowed within ``productionlist`` directive arguments. |
| |
| The definition can contain token names which are marked as interpreted text |
n | (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references |
n | (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references |
| to the productions of these tokens. Note that vertical bars used to indicate |
| to the productions of these tokens. |
| alternatives must be escaped with backslashes because otherwise they would |
| indicate a substitution reference to the reST parser. |
| |
n | Note that no further reST parsing is done in the production, so that you |
| don't have to escape ``*`` or ``|`` characters. |
| |
n | |
| .. XXX describe optional first parameter |
| .. XXX describe optional first parameter |
| |
| The following is an example taken from the Python Reference Manual:: |
| |
| .. productionlist:: |
n | try_stmt: try1_stmt \| try2_stmt |
n | try_stmt: try1_stmt | try2_stmt |
| try1_stmt: "try" ":" :token:`suite` |
| try1_stmt: "try" ":" `suite` |
| : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ |
| : ("except" [`expression` ["," `target`]] ":" `suite`)+ |
| : ["else" ":" :token:`suite`] |
| : ["else" ":" `suite`] |
| : ["finally" ":" :token:`suite`] |
| : ["finally" ":" `suite`] |
| try2_stmt: "try" ":" :token:`suite` |
| try2_stmt: "try" ":" `suite` |
| : "finally" ":" :token:`suite` |
| : "finally" ":" `suite` |
| |
| |
| Substitutions |
| ------------- |
| |
| The documentation system provides three substitutions that are defined by default. |
n | They are set in the build configuration file, see :ref:`doc-build-config`. |
n | They are set in the build configuration file :file:`conf.py`. |
| |
| .. describe:: |release| |
| |
| Replaced by the Python release the documentation refers to. This is the full |
| version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. |
| |
| .. describe:: |version| |
| |
| Replaced by the Python version the documentation refers to. This consists |
| only of the major and minor version parts, e.g. ``2.5``, even for version |
| 2.5.1. |
| |
| .. describe:: |today| |
| |
| Replaced by either today's date, or the date set in the build configuration |
| file. Normally has the format ``April 14, 2007``. |
t | |
| |
| .. rubric:: Footnotes |
| |
| .. [1] There is a standard ``.. include`` directive, but it raises errors if the |
| file is not found. This one only emits a warning. |