FCL/sf/adapt/qemu: comparison symbian-qemu-0.9.1-12/python-2.6.1/Doc/documenting/markup.rst

equal deleted inserted replaced

-:ffa851df0825
+:2fb8b9db1c86
+.. highlightlang:: rest
+Additional Markup Constructs
+============================
+Sphinx adds a lot of new directives and interpreted text roles to standard reST
+markup.  This section contains the reference material for these facilities.
+Documentation for "standard" reST constructs is not included here, though
+they are used in the Python documentation.
+File-wide metadata
+------------------
+reST has the concept of "field lists"; these are a sequence of fields marked up
+like this::
+:Field name: Field content
+A field list at the very top of a file is parsed as the "docinfo", which in
+normal documents can be used to record the author, date of publication and
+other metadata.  In Sphinx, the docinfo is used as metadata, too, but not
+displayed in the output.
+At the moment, only one metadata field is recognized:
+``nocomments``
+If set, the web application won't display a comment form for a page generated
+from this source file.
+Meta-information markup
+-----------------------
+.. describe:: sectionauthor
+Identifies the author of the current section.  The argument should include
+the author's name such that it can be used for presentation (though it isn't)
+and email address.  The domain name portion of the address should be lower
+case.  Example::
+.. sectionauthor:: Guido van Rossum <guido@python.org>
+Currently, this markup isn't reflected in the output in any way, but it helps
+keep track of contributions.
+Module-specific markup
+----------------------
+The markup described in this section is used to provide information about a
+module being documented.  Each module should be documented in its own file.
+Normally this markup appears after the title heading of that file; a typical
+file might start like this::
+:mod:`parrot` -- Dead parrot access
+===================================
+.. module:: parrot
+:platform: Unix, Windows
+:synopsis: Analyze and reanimate dead parrots.
+.. moduleauthor:: Eric Cleese <eric@python.invalid>
+.. moduleauthor:: John Idle <john@python.invalid>
+As you can see, the module-specific markup consists of two directives, the
+``module`` directive and the ``moduleauthor`` directive.
+.. describe:: module
+This directive marks the beginning of the description of a module (or package
+submodule, in which case the name should be fully qualified, including the
+package name).
+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 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.
+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.
+.. 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.
+Information units
+-----------------
+There are a number of directives used to describe specific features provided by
+modules.  Each directive requires one or more signatures to provide basic
+information about what is being described, and the content should be the
+description.  The basic version makes entries in the general index; if no index
+entry is desired, you can give the directive option flag ``:noindex:``.  The
+following example shows all of the features of this directive type::
+.. function:: spam(eggs)
+ham(eggs)
+:noindex:
+Spam or ham the foo.
+The signatures of object methods or data attributes should always include the
+type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
+context which type they belong to; this is to enable consistent
+cross-references.  If you describe methods belonging to an abstract protocol,
+such as "context managers", include a (pseudo-)type name too to make the
+index entries more informative.
+The directives are:
+.. describe:: cfunction
+Describes a C function. The signature should be given as in C, e.g.::
+.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+This is also used to describe function-like preprocessor macros.  The names
+of the arguments should be given so they may be used in the description.
+Note that you don't have to backslash-escape asterisks in the signature,
+as it is not parsed by the reST inliner.
+.. describe:: cmember
+Describes a C struct member. Example signature::
+.. cmember:: PyObject* PyTypeObject.tp_bases
+The text of the description should include the range of values allowed, how
+the value should be interpreted, and whether the value can be changed.
+References to structure members in text should use the ``member`` role.
+.. describe:: cmacro
+Describes a "simple" C macro.  Simple macros are macros which are used
+for code expansion, but which do not take arguments so cannot be described as
+functions.  This is not to be used for simple constant definitions.  Examples
+of its use in the Python documentation include :cmacro:`PyObject_HEAD` and
+:cmacro:`Py_BEGIN_ALLOW_THREADS`.
+.. describe:: ctype
+Describes a C type. The signature should just be the type name.
+.. describe:: cvar
+Describes a global C variable.  The signature should include the type, such
+as::
+.. cvar:: PyObject* PyClass_Type
+.. describe:: data
+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.
+.. describe:: exception
+Describes an exception class.  The signature can, but need not include
+parentheses with constructor arguments.
+.. describe:: function
+Describes a module-level function.  The signature should include the
+parameters, enclosing optional parameters in brackets.  Default values can be
+given if it enhances clarity.  For example::
+.. function:: Timer.repeat([repeat=3[, number=1000000]])
+Object methods are not documented using this directive. Bound object methods
+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
+how they are used (especially whether mutable objects passed as parameters
+are modified), side effects, and possible exceptions.  A small example may be
+provided.
+.. describe:: class
+Describes a class.  The signature can include parentheses with parameters
+which will be shown as the constructor arguments.
+.. describe:: attribute
+Describes an object data attribute.  The description should include
+information about the type of the data to be expected and whether it may be
+changed directly.
+.. describe:: method
+Describes an object method.  The parameters should not include the ``self``
+parameter.  The description should include similar information to that
+described for ``function``.
+.. describe:: opcode
+Describes a Python :term:`bytecode` instruction.
+.. describe:: cmdoption
+Describes a command line option or switch.  Option argument names should be
+enclosed in angle brackets.  Example::
+.. cmdoption:: -m <module>
+Run a module as a script.
+.. describe:: envvar
+Describes an environment variable that Python uses or defines.
+There is also a generic version of these directives:
+.. describe:: describe
+This directive produces the same formatting as the specific ones explained
+above but does not create index entries or cross-referencing targets.  It is
+used, for example, to describe the directives in this document. Example::
+.. describe:: opcode
+Describes a Python bytecode instruction.
+Showing code examples
+---------------------
+Examples of Python source code or interactive sessions are represented using
+standard reST literal blocks.  They are started by a ``::`` at the end of the
+preceding paragraph and delimited by indentation.
+Representing an interactive session requires including the prompts and output
+along with the Python code.  No special markup is required for interactive
+sessions.  After the last line of input or output presented, there should not be
+an "unused" primary prompt; this is an example of what *not* to do::
+>>> 1 + 1
+2
+>>>
+Syntax highlighting is handled in a smart way:
+* There is a "highlighting language" for each source file.  Per default,
+this is ``'python'`` as the majority of files will have to highlight Python
+snippets.
+* Within Python highlighting mode, interactive sessions are recognized
+automatically and highlighted appropriately.
+* 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.
+* The valid values 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
+``literalinclude`` directive. [1]_ For example, to include the Python source file
+:file:`example.py`, use::
+.. literalinclude:: example.py
+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.
+Variable names are an exception, they should be marked simply with ``*var*``.
+For all other roles, you have to write ``:rolename:`content```.
+.. note::
+For all cross-referencing roles, if you prefix the content with ``!``, no
+reference/hyperlink will be created.
+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
+should not include trailing parentheses to enhance readability.  The
+parentheses are stripped when searching for identifiers.
+.. describe:: data
+The name of a module-level variable.
+.. 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
+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.
+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
+The name of a C-language variable.
+.. describe:: cfunc
+The name of a C-language function. Should include trailing parentheses.
+.. describe:: cmacro
+The name of a "simple" C macro, as defined above.
+.. describe:: ctype
+The name of a C-language type.
+The following role does possibly create a cross-reference, but does not refer
+to objects:
+.. describe:: token
+The name of a grammar token (used in the reference manual to create links
+between production displays).
+The following role creates a cross-reference to the term in the glossary:
+.. describe:: term
+Reference to a term in the glossary.  The glossary is created using the
+``glossary`` directive containing a definition list with terms and
+definitions.  It does not have to be in the same file as the ``term``
+markup, in fact, by default the Python docs have one global glossary
+in the ``glossary.rst`` file.
+If you use a term that's not explained in a glossary, you'll get a warning
+during build.
+---------
+The following roles don't do anything special except formatting the text
+in a different style:
+.. describe:: command
+The name of an OS-level command, such as ``rm``.
+.. describe:: dfn
+Mark the defining instance of a term in the text.  (No index entries are
+generated.)
+.. describe:: envvar
+An environment variable.  Index entries are generated.
+.. describe:: file
+The name of a file or directory.  Within the contents, you can use curly
+braces to indicate a "variable" part, for example::
+... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
+In the built documentation, the ``x`` will be displayed differently to
+indicate that it is to be replaced by the Python minor version.
+.. describe:: guilabel
+Labels presented as part of an interactive user interface should be marked
+using ``guilabel``.  This includes labels from text-based interfaces such as
+those created using :mod:`curses` or other text-based libraries.  Any label
+used in the interface should be marked with this role, including button
+labels, window titles, field names, menu and menu selection names, and even
+values in selection lists.
+.. describe:: kbd
+Mark a sequence of keystrokes.  What form the key sequence takes may depend
+on platform- or application-specific conventions.  When there are no relevant
+conventions, the names of modifier keys should be spelled out, to improve
+accessibility for new users and non-native speakers.  For example, an
+*xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
+reference to a specific application or platform, the same sequence should be
+marked as ``:kbd:`Control-x Control-f```.
+.. describe:: keyword
+The name of a keyword in Python.
+.. describe:: mailheader
+The name of an RFC 822-style mail header.  This markup does not imply that
+the header is being used in an email message, but can be used to refer to any
+header of the same "style."  This is also used for headers defined by the
+various MIME specifications.  The header name should be entered in the same
+way it would normally be found in practice, with the camel-casing conventions
+being preferred where there is more than one common usage. For example:
+``:mailheader:`Content-Type```.
+.. describe:: makevar
+The name of a :command:`make` variable.
+.. describe:: manpage
+A reference to a Unix manual page including the section,
+e.g. ``:manpage:`ls(1)```.
+.. describe:: menuselection
+Menu selections should be marked using the ``menuselection`` role.  This is
+used to mark a complete sequence of menu selections, including selecting
+submenus and choosing a specific operation, or any subsequence of such a
+sequence.  The names of individual selections should be separated by
+``-->``.
+For example, to mark the selection "Start > Programs", use this markup::
+:menuselection:`Start --> Programs`
+When including a selection that includes some trailing indicator, such as the
+ellipsis some operating systems use to indicate that the command opens a
+dialog, the indicator should be omitted from the selection name.
+.. describe:: mimetype
+The name of a MIME type, or a component of a MIME type (the major or minor
+portion, taken alone).
+.. describe:: newsgroup
+The name of a Usenet newsgroup.
+.. describe:: option
+A command-line option to an executable program.  The leading hyphen(s) must
+be included.
+.. describe:: program
+The name of an executable program.  This may differ from the file name for
+the executable for some platforms.  In particular, the ``.exe`` (or other)
+extension should be omitted for Windows programs.
+.. describe:: regexp
+A regular expression. Quotes should not be included.
+.. describe:: samp
+A piece of literal text, such as code.  Within the contents, you can use
+curly braces to indicate a "variable" part, as in ``:file:``.
+If you don't need the "variable part" indication, use the standard
+````code```` instead.
+.. describe:: var
+A Python or C variable or parameter name.
+The following roles generate external links:
+.. describe:: pep
+A reference to a Python Enhancement Proposal.  This generates appropriate
+index entries. The text "PEP *number*\ " is generated; in the HTML output,
+this text is a hyperlink to an online copy of the specified PEP.
+.. describe:: rfc
+A reference to an Internet Request for Comments.  This generates appropriate
+index entries. The text "RFC *number*\ " is generated; in the HTML output,
+this text is a hyperlink to an online copy of the specified RFC.
+Note that there are no special roles for including hyperlinks as you can use
+the standard reST markup for that purpose.
+.. _doc-ref-role:
+Cross-linking markup
+--------------------
+To support cross-referencing to arbitrary sections in the documentation, the
+standard reST labels are "abused" a bit: Every label must precede a section
+title; and every label name must be unique throughout the entire documentation
+source.
+You can then reference to these sections using the ``:ref:`label-name``` role.
+Example::
+.. _my-reference-label:
+Section to cross-reference
+--------------------------
+This is the text of the section.
+It refers to the section itself, see :ref:`my-reference-label`.
+The ``:ref:`` invocation is replaced with the section title.
+Paragraph-level markup
+----------------------
+These directives create short paragraphs and can be used inside information
+units as well as normal text:
+.. describe:: note
+An especially important bit of information about an API that a user should be
+aware of when using whatever bit of API the note pertains to.  The content of
+the directive should be written in complete sentences and include all
+appropriate punctuation.
+Example::
+.. note::
+This function is not suitable for sending spam e-mails.
+.. describe:: warning
+An important bit of information about an API that a user should be very aware
+of when using whatever bit of API the warning pertains to.  The content of
+the directive should be written in complete sentences and include all
+appropriate punctuation. This differs from ``note`` in that it is recommended
+over ``note`` for information regarding security.
+.. describe:: versionadded
+This directive documents the version of Python which added the described
+feature to the library or C API. When this applies to an entire module, it
+should be placed at the top of the module section before any prose.
+The first argument must be given and is the version in question; you can add
+a second argument consisting of a *brief* explanation of the change.
+Example::
+.. versionadded:: 2.5
+The `spam` parameter.
+Note that there must be no blank line between the directive head and the
+explanation; this is to make these blocks visually continuous in the markup.
+.. describe:: versionchanged
+Similar to ``versionadded``, but describes when and what changed in the named
+feature in some way (new parameters, changed side effects, etc.).
+--------------
+.. describe:: seealso
+Many sections include a list of references to module documentation or
+external documents.  These lists are created using the ``seealso`` directive.
+The ``seealso`` directive is typically placed in a section just before any
+sub-sections.  For the HTML output, it is shown boxed off from the main flow
+of the text.
+The content of the ``seealso`` directive should be a reST definition list.
+Example::
+.. seealso::
+Module :mod:`zipfile`
+Documentation of the :mod:`zipfile` standard module.
+`GNU tar manual, Basic Tar Format <http://link>`_
+Documentation for tar archive files, including GNU tar extensions.
+.. describe:: rubric
+This directive creates a paragraph heading that is not used to create a
+table of contents node.  It is currently used for the "Footnotes" caption.
+.. describe:: centered
+This directive creates a centered boldfaced paragraph.  Use it as follows::
+.. centered::
+Paragraph contents.
+Table-of-contents markup
+------------------------
+Since reST does not have facilities to interconnect several documents, or split
+documents into multiple output files, Sphinx uses a custom directive to add
+relations between the single files the documentation is made of, as well as
+tables of contents.  The ``toctree`` directive is the central element.
+.. describe:: toctree
+This directive inserts a "TOC tree" at the current location, using the
+individual TOCs (including "sub-TOC trees") of the files given in the
+directive body.  A numeric ``maxdepth`` option may be given to indicate the
+depth of the tree; by default, all levels are included.
+Consider this example (taken from the library reference index)::
+.. toctree::
+:maxdepth: 2
+intro.rst
+strings.rst
+datatypes.rst
+numeric.rst
+(many more files listed here)
+This accomplishes two things:
+* Tables of contents from all those files are inserted, with a maximum depth
+of two, that means one nested heading.  ``toctree`` directives in those
+files are also taken into account.
+* Sphinx knows that the relative order of the files ``intro.rst``,
+``strings.rst`` and so forth, and it knows that they are children of the
+shown file, the library index.  From this information it generates "next
+chapter", "previous chapter" and "parent chapter" links.
+In the end, all files included in the build process must occur in one
+``toctree`` directive; Sphinx will emit a warning if it finds a file that is
+not included, because that means that this file will not be reachable through
+standard navigation.
+The special file ``contents.rst`` at the root of the source directory is the
+"root" of the TOC tree hierarchy; from it the "Contents" page is generated.
+Index-generating markup
+-----------------------
+Sphinx automatically creates index entries from all information units (like
+functions, classes or attributes) like discussed before.
+However, there is also an explicit directive available, to make the index more
+comprehensive and enable index entries in documents where information is not
+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::
+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
+subentry text with a semicolon (this notation is also used below to describe
+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
+``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``.
+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
+displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
+the definition of the symbol.  There is this directive:
+.. describe:: productionlist
+This directive is used to enclose a group of productions.  Each production is
+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
+(e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
+to the productions of these tokens.
+Note that no further reST parsing is done in the production, so that you
+don't have to escape ``*`` or ``|`` characters.
+.. XXX describe optional first parameter
+The following is an example taken from the Python Reference Manual::
+.. productionlist::
+try_stmt: try1_stmt | try2_stmt
+try1_stmt: "try" ":" `suite`
+: ("except" [`expression` ["," `target`]] ":" `suite`)+
+: ["else" ":" `suite`]
+: ["finally" ":" `suite`]
+try2_stmt: "try" ":" `suite`
+: "finally" ":" `suite`
+Substitutions
+-------------
+The documentation system provides three substitutions that are defined by default.
+They are set in the build configuration file, see :ref:`doc-build-config`.
+.. 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``.
+.. 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.