From 06dd99e1a1c759599832a62e686771f3ffea9722 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 15 Mar 2008 09:06:04 +0000 Subject: [PATCH] Expand the markup chapter a bit. --- doc/concepts.rst | 54 ++- doc/contents.rst | 2 +- doc/glossary.rst | 6 + doc/markup.rst | 835 --------------------------------------- doc/markup/code.rst | 94 +++++ doc/markup/index.rst | 15 + doc/markup/infounits.rst | 197 +++++++++ doc/markup/inline.rst | 311 +++++++++++++++ doc/markup/misc.rst | 41 ++ doc/markup/para.rst | 185 +++++++++ 10 files changed, 899 insertions(+), 841 deletions(-) delete mode 100644 doc/markup.rst create mode 100644 doc/markup/code.rst create mode 100644 doc/markup/index.rst create mode 100644 doc/markup/infounits.rst create mode 100644 doc/markup/inline.rst create mode 100644 doc/markup/misc.rst create mode 100644 doc/markup/para.rst diff --git a/doc/concepts.rst b/doc/concepts.rst index 7e10b3032..cb40be2f7 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -1,14 +1,58 @@ +.. highlight:: rest + .. _concepts: Sphinx concepts =============== - -The TOC tree ------------- - - Document names -------------- + + +The TOC tree +------------ + +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. + +.. directive:: 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 Python docs' 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. Use :confval:`unused_documents` to explicitly exclude + documents from this check. + + The "master file" (selected by :confval:`master_file`) is the "root" of the + TOC tree hierarchy. It can be used as the documentation's main page, or as a + "full table of contents" if you don't give a ``maxdepth`` option. diff --git a/doc/contents.rst b/doc/contents.rst index ef1bf717c..9336e51e1 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -9,7 +9,7 @@ Sphinx documentation contents intro.rst concepts.rst rest.rst - markup.rst + markup/index.rst builders.rst config.rst templating.rst diff --git a/doc/glossary.rst b/doc/glossary.rst index 662d0a9ca..d75f814a3 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -20,3 +20,9 @@ Glossary documentation root The directory which contains the documentation's :file:`conf.py` file and is therefore seen as one Sphinx project. + + environment + A structure where information about all documents under the root is saved, + and used for cross-referencing. The environment is pickled after the + parsing stage, so that successive runs only need to read and parse new and + changed documents. diff --git a/doc/markup.rst b/doc/markup.rst deleted file mode 100644 index 437dcc49f..000000000 --- a/doc/markup.rst +++ /dev/null @@ -1,835 +0,0 @@ -.. highlight:: rest - :linenothreshold: 5 - -.. XXX missing: glossary - - -Sphinx 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. - - -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 ------------------------ - -.. directive:: sectionauthor - - Identifies the author of the current section. The argument should include - the author's name such that it can be used for presentation and email - address. The domain name portion of the address should be lower case. - Example:: - - .. sectionauthor:: Guido van Rossum - - By default, this markup isn't reflected in the output in any way (it helps - keep track of contributions), but you can set the configuration value - :confval:`show_authors` to True to make them produce a paragraph in the - output. - - -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 - .. moduleauthor:: John Idle - -As you can see, the module-specific markup consists of two directives, the -``module`` directive and the ``moduleauthor`` directive. - -.. directive:: 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. - -.. directive:: 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 only produces output if the - :confval:`show_authors` configuration value is True. - - -.. 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: - -.. directive:: 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. - -.. directive:: 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. - -.. directive:: 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`. - -.. directive:: ctype - - Describes a C type. The signature should just be the type name. - -.. directive:: cvar - - Describes a global C variable. The signature should include the type, such - as:: - - .. cvar:: PyObject* PyClass_Type - -.. directive:: 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. - -.. directive:: exception - - Describes an exception class. The signature can, but need not include - parentheses with constructor arguments. - -.. directive:: 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. - -.. directive:: class - - Describes a class. The signature can include parentheses with parameters - which will be shown as the constructor arguments. - -.. directive:: 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. - -.. directive:: method - - Describes an object method. The parameters should not include the ``self`` - parameter. The description should include similar information to that - described for ``function``. - -.. directive:: opcode - - Describes a Python bytecode instruction (this is not very useful for projects - other than Python itself). - -.. directive:: cmdoption - - Describes a command line option or switch. Option argument names should be - enclosed in angle brackets. Example:: - - .. cmdoption:: -m - - Run a module as a script. - -.. directive:: envvar - - Describes an environment variable that the documented code uses or defines. - - -There is also a generic version of these directives: - -.. directive:: 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: - -.. role:: mod - - The name of a module; a dotted name may be used. This should also be used for - package names. - -.. role:: func - - The name of a Python function; dotted names may be used. The role text - should include trailing parentheses to enhance readability. The parentheses - are stripped when searching for identifiers. - -.. role:: data - - The name of a module-level variable. - -.. role:: 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. - -.. role:: class - - A class name; a dotted name may be used. - -.. role:: meth - - The name of a method of an object. The role text should include the type - name, method name and the trailing parentheses. A dotted name may be used. - -.. role:: attr - - The name of a data attribute of an object. - -.. role:: 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: - -.. role:: cdata - - The name of a C-language variable. - -.. role:: cfunc - - The name of a C-language function. Should include trailing parentheses. - -.. role:: cmacro - - The name of a "simple" C macro, as defined above. - -.. role:: ctype - - The name of a C-language type. - - -The following roles do possibly create a cross-reference, but do not refer -to objects: - -.. role:: token - - The name of a grammar token (used in the reference manual to create links - between production displays). - -.. role:: keyword - - The name of a keyword in Python. This creates a link to a reference label - with that name, if it exists. - - -The following role creates a cross-reference to the term in the glossary: - -.. role:: 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, - for example 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: - -.. role:: command - - The name of an OS-level command, such as ``rm``. - -.. role:: dfn - - Mark the defining instance of a term in the text. (No index entries are - generated.) - -.. role:: envvar - - An environment variable. Index entries are generated. - -.. role:: 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. - -.. role:: 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. - -.. role:: 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```. - -.. role:: 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```. - -.. role:: makevar - - The name of a :command:`make` variable. - -.. role:: manpage - - A reference to a Unix manual page including the section, - e.g. ``:manpage:`ls(1)```. - -.. role:: 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. - -.. role:: mimetype - - The name of a MIME type, or a component of a MIME type (the major or minor - portion, taken alone). - -.. role:: newsgroup - - The name of a Usenet newsgroup. - -.. role:: option - - A command-line option to an executable program. The leading hyphen(s) must - be included. - -.. role:: 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. - -.. role:: regexp - - A regular expression. Quotes should not be included. - -.. role:: 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. - -.. role:: var - - A Python or C variable or parameter name. - - -The following roles generate external links: - -.. role:: 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. - -.. role:: 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 --------------------- - -.. XXX add new :ref: syntax alternative - -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: - -.. directive:: 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. - -.. directive:: 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. - -.. directive:: versionadded - - This directive documents the version of the project 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. - -.. directive:: versionchanged - - Similar to ``versionadded``, but describes when and what changed in the named - feature in some way (new parameters, changed side effects, etc.). - --------------- - -.. directive:: 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 `_ - Documentation for tar archive files, including GNU tar extensions. - -.. directive:: 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. - -.. directive:: 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. - -.. directive:: 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: - -.. directive:: 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 project release the documentation refers to. This is meant - to be the full version string including alpha/beta/release candidate tags, - e.g. ``2.5.2b3``. - -.. describe:: |version| - - Replaced by the project version the documentation refers to. This is meant to - consist 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. diff --git a/doc/markup/code.rst b/doc/markup/code.rst new file mode 100644 index 000000000..ab1420c2c --- /dev/null +++ b/doc/markup/code.rst @@ -0,0 +1,94 @@ +.. highlight:: rest + +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 done with `Pygments `_ (if it's +installed) and 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 ``highlight`` directive, + used as follows:: + + .. highlight:: c + + This language is used until the next ``highlight`` directive is encountered. + +* For documents that have to show snippets in different languages, there's also + a :dir:`code-block` directive that is given the highlighting language + directly:: + + .. code-block:: ruby + + Some Ruby code. + + The directive's alias name :dir:`sourcecode` works as well. + +* The valid values for the highlighting language are: + + * ``none`` (no highlighting) + * ``python`` (the default) + * ``rest`` + * ``c`` + * ... and any other lexer name that Pygments supports. + +* If highlighting with the selected language fails, the block is not highlighted + in any way. + +Line numbers +^^^^^^^^^^^^ + +If installed, Pygments can generate line numbers for code blocks. For +automatically-highlighted blocks (those started by ``::``), line numbers must be +switched on in a :dir:`highlight` directive, with the ``linenothreshold`` +option:: + + .. highlight:: python + :linenothreshold: 5 + +This will produce line numbers for all code blocks longer than five lines. + +For :dir:`code-block` blocks, a ``linenos`` flag option can be given to switch +on line numbers for the individual block:: + + .. code-block:: ruby + :linenos: + + Some more Ruby code. + + +Includes +^^^^^^^^ + +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. + + +.. 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. diff --git a/doc/markup/index.rst b/doc/markup/index.rst new file mode 100644 index 000000000..5d9da19cd --- /dev/null +++ b/doc/markup/index.rst @@ -0,0 +1,15 @@ +.. XXX missing: glossary + +Sphinx 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. + +.. toctree:: + + infounits.rst + para.rst + code.rst + inline.rst + misc.rst diff --git a/doc/markup/infounits.rst b/doc/markup/infounits.rst new file mode 100644 index 000000000..7360ff2c5 --- /dev/null +++ b/doc/markup/infounits.rst @@ -0,0 +1,197 @@ +.. highlight:: rest + +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 + .. moduleauthor:: John Idle + +As you can see, the module-specific markup consists of two directives, the +``module`` directive and the ``moduleauthor`` directive. + +.. directive:: 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. + +.. directive:: 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 only produces output if the + :confval:`show_authors` configuration value is True. + + +.. 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: + +.. directive:: 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. + +.. directive:: 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. + +.. directive:: 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`. + +.. directive:: ctype + + Describes a C type. The signature should just be the type name. + +.. directive:: cvar + + Describes a global C variable. The signature should include the type, such + as:: + + .. cvar:: PyObject* PyClass_Type + +.. directive:: 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. + +.. directive:: exception + + Describes an exception class. The signature can, but need not include + parentheses with constructor arguments. + +.. directive:: 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. + +.. directive:: class + + Describes a class. The signature can include parentheses with parameters + which will be shown as the constructor arguments. + +.. directive:: 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. + +.. directive:: method + + Describes an object method. The parameters should not include the ``self`` + parameter. The description should include similar information to that + described for ``function``. + +.. directive:: opcode + + Describes a Python bytecode instruction (this is not very useful for projects + other than Python itself). + +.. directive:: cmdoption + + Describes a command line option or switch. Option argument names should be + enclosed in angle brackets. Example:: + + .. cmdoption:: -m + + Run a module as a script. + +.. directive:: envvar + + Describes an environment variable that the documented code uses or defines. + + +There is also a generic version of these directives: + +.. directive:: 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. diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst new file mode 100644 index 000000000..d0f52342a --- /dev/null +++ b/doc/markup/inline.rst @@ -0,0 +1,311 @@ +.. highlight:: rest + +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: + +.. role:: mod + + The name of a module; a dotted name may be used. This should also be used for + package names. + +.. role:: func + + The name of a Python function; dotted names may be used. The role text + should include trailing parentheses to enhance readability. The parentheses + are stripped when searching for identifiers. + +.. role:: data + + The name of a module-level variable. + +.. role:: 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. + +.. role:: class + + A class name; a dotted name may be used. + +.. role:: meth + + The name of a method of an object. The role text should include the type + name, method name and the trailing parentheses. A dotted name may be used. + +.. role:: attr + + The name of a data attribute of an object. + +.. role:: 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: + +.. role:: cdata + + The name of a C-language variable. + +.. role:: cfunc + + The name of a C-language function. Should include trailing parentheses. + +.. role:: cmacro + + The name of a "simple" C macro, as defined above. + +.. role:: ctype + + The name of a C-language type. + + +The following roles do possibly create a cross-reference, but do not refer +to objects: + +.. role:: token + + The name of a grammar token (used in the reference manual to create links + between production displays). + +.. role:: keyword + + The name of a keyword in Python. This creates a link to a reference label + with that name, if it exists. + + +The following role creates a cross-reference to the term in the glossary: + +.. role:: 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, + for example 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: + +.. role:: command + + The name of an OS-level command, such as ``rm``. + +.. role:: dfn + + Mark the defining instance of a term in the text. (No index entries are + generated.) + +.. role:: envvar + + An environment variable. Index entries are generated. + +.. role:: 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. + +.. role:: 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. + +.. role:: 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```. + +.. role:: 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```. + +.. role:: makevar + + The name of a :command:`make` variable. + +.. role:: manpage + + A reference to a Unix manual page including the section, + e.g. ``:manpage:`ls(1)```. + +.. role:: 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. + +.. role:: mimetype + + The name of a MIME type, or a component of a MIME type (the major or minor + portion, taken alone). + +.. role:: newsgroup + + The name of a Usenet newsgroup. + +.. role:: option + + A command-line option to an executable program. The leading hyphen(s) must + be included. + +.. role:: 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. + +.. role:: regexp + + A regular expression. Quotes should not be included. + +.. role:: 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. + +.. role:: var + + A Python or C variable or parameter name. + + +The following roles generate external links: + +.. role:: 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. + +.. role:: 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. + + +Substitutions +------------- + +The documentation system provides three substitutions that are defined by default. +They are set in the build configuration file. + +.. describe:: |release| + + Replaced by the project release the documentation refers to. This is meant + to be the full version string including alpha/beta/release candidate tags, + e.g. ``2.5.2b3``. Set by :confval:`release`. + +.. describe:: |version| + + Replaced by the project version the documentation refers to. This is meant to + consist only of the major and minor version parts, e.g. ``2.5``, even for + version 2.5.1. Set by :confval:`version`. + +.. describe:: |today| + + Replaced by either today's date, or the date set in the build configuration + file. Normally has the format ``April 14, 2007``. Set by + :confval:`today_fmt` and :confval:`today`. + + +.. _doc-ref-role: + +Cross-linking markup +-------------------- + +To support cross-referencing to arbitrary sections in the documentation, the +standard reST labels used. Of course, for this to work label names must be +unique throughout the entire documentation. There are two ways in which you can +refer to labels: + +* If you place a label directly before a section title, you can reference to it + with ``:ref:`label-name```. 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:`` role would then generate a link to the section, with the link + title being "Section to cross-reference". + +* Labels that aren't placed before a section title can still be referenced to, + but you must give the link an explicit title, using this syntax: ``:ref:`Link + title ```. diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst new file mode 100644 index 000000000..8a0ba3dbb --- /dev/null +++ b/doc/markup/misc.rst @@ -0,0 +1,41 @@ +.. highlight:: rest + +Miscellaneous markup +==================== + +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 +----------------------- + +.. directive:: sectionauthor + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation and email + address. The domain name portion of the address should be lower case. + Example:: + + .. sectionauthor:: Guido van Rossum + + By default, this markup isn't reflected in the output in any way (it helps + keep track of contributions), but you can set the configuration value + :confval:`show_authors` to True to make them produce a paragraph in the + output. diff --git a/doc/markup/para.rst b/doc/markup/para.rst new file mode 100644 index 000000000..89d6dd05a --- /dev/null +++ b/doc/markup/para.rst @@ -0,0 +1,185 @@ +.. highlight:: rest + +Paragraph-level markup +---------------------- + +These directives create short paragraphs and can be used inside information +units as well as normal text: + +.. directive:: 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. + +.. directive:: 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. + +.. directive:: versionadded + + This directive documents the version of the project 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. + +.. directive:: versionchanged + + Similar to ``versionadded``, but describes when and what changed in the named + feature in some way (new parameters, changed side effects, etc.). + +-------------- + +.. directive:: 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 `_ + Documentation for tar archive files, including GNU tar extensions. + +.. directive:: 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. + +.. directive:: centered + + This directive creates a centered boldfaced paragraph. Use it as follows:: + + .. centered:: + + Paragraph contents. + + +Table-of-contents markup +------------------------ + +The :dir:`toctree` directive, which generates tables of contents of +subdocuments, is described in "Sphinx concepts". + +For local tables of contents, use the standard reST :dir:`contents` directive. + + +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: + +.. directive:: 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`