diff options
| -rw-r--r-- | doc/builders.rst | 53 | ||||
| -rw-r--r-- | doc/concepts.rst | 55 | ||||
| -rw-r--r-- | doc/config.rst | 4 | ||||
| -rw-r--r-- | doc/contents.rst | 18 | ||||
| -rw-r--r-- | doc/ext.py | 38 | ||||
| -rw-r--r-- | doc/ext/appapi.rst (renamed from doc/ext/api.rst) | 0 | ||||
| -rw-r--r-- | doc/ext/builderapi.rst | 24 | ||||
| -rw-r--r-- | doc/extensions.rst | 13 | ||||
| -rw-r--r-- | doc/intro.rst | 2 | ||||
| -rw-r--r-- | doc/markup/code.rst | 25 | ||||
| -rw-r--r-- | doc/markup/desc.rst (renamed from doc/markup/infounits.rst) | 36 | ||||
| -rw-r--r-- | doc/markup/index.rst | 12 | ||||
| -rw-r--r-- | doc/markup/inline.rst | 144 | ||||
| -rw-r--r-- | doc/markup/para.rst | 95 |
14 files changed, 353 insertions, 166 deletions
diff --git a/doc/builders.rst b/doc/builders.rst index 6ba2147ce..c1625b476 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -1,23 +1,68 @@ .. _builders: -Builders and the environment -============================ +Available builders +================== .. module:: sphinx.builder :synopsis: Available built-in builder classes. +These are the built-in Sphinx builders. More builders can be added by +:ref:`extensions <extensions>`. + +The builder's "name" must be given to the **-b** command-line option of +:program:`sphinx-build.py` to select a builder. -.. class:: Builder .. class:: StandaloneHTMLBuilder -.. class:: WebHTMLBuilder + This is the standard HTML builder. Its output is a directory with HTML + files, complete with style sheets and optionally the reST sources. There are + quite a few configuration values that customize the output of this builder, + see the chapter :ref:`html-options` for details. + + Its name is ``html``. .. class:: HTMLHelpBuilder + This builder produces the same output as the standalone HTML builder, but + also generates HTML Help support files that allow the Microsoft HTML Help + Workshop to compile them into a CHM file. + + Its name is ``htmlhelp``. + +.. class:: WebHTMLBuilder + + This builder produces a directory with pickle files containing mostly HTML + fragments and TOC information, for use of a web application (or custom + postprocessing tool) that doesn't use the standard HTML templates. + + It also is the format used by the Sphinx Web application. Its name is + ``web``. + .. class:: LaTeXBuilder + This builder produces a bunch of LaTeX files in the output directory. You + have to specify which documents are to be included in which LaTeX files via + the :confval:`latex_documents` configuration value. There are a few + configuration values that customize the output of this builder, see the + chapter :ref:`latex-options` for details. + + Its name is ``latex``. + .. class:: ChangesBuilder + This builder produces an HTML overview of all :dir:`versionadded`, + :dir:`versionchanged` and :dir:`deprecated` directives for the current + :confval:`version`. This is useful to generate a ChangeLog file, for + example. + + Its name is ``changes``. + .. class:: CheckExternalLinksBuilder + This builder scans all documents for external links, tries to open them with + :mod:`urllib2`, and writes an overview which ones are broken and redirected + to standard output and to :file:`output.txt` in the output directory. + + Its name is ``linkcheck``. + diff --git a/doc/concepts.rst b/doc/concepts.rst index cb40be2f7..662665d0a 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -8,12 +8,20 @@ Sphinx concepts Document names -------------- - +Since the reST source files can have different extensions (some people like +``.txt``, some like ``.rst`` -- the extension can be configured with +:confval:`source_suffix`) and different OSes have different path separators, +Sphinx abstracts them: all "document names" are relative to the +:term:`documentation root`, the extension is stripped, and path separators are +converted to slashes. All values, parameters and suchlike referring to +"documents" expect such a document name. The TOC tree ------------ +.. index:: pair: table of; contents + 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 @@ -22,37 +30,38 @@ 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. + individual TOCs (including "sub-TOC trees") of the documents given in the + directive body (whose path is relative to the document the directive occurs + in). 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) + intro + strings + datatypes + numeric + (many more documents 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 + * Tables of contents from all those documents are inserted, with a maximum + depth of two, that means one nested heading. ``toctree`` directives in + those documents are also taken into account. + * Sphinx knows that the relative order of the documents ``intro``, + ``strings`` and so forth, and it knows that they are children of the shown + document, 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. + In the end, all documents under the :term:`documentation root` 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. + The "master document" (selected by :confval:`master_doc`) 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/config.rst b/doc/config.rst index 0832fbf96..0c0b253b5 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -119,6 +119,8 @@ General configuration style. +.. _html-options: + Options for HTML output ----------------------- @@ -175,6 +177,8 @@ that use Sphinx' HTMLWriter class. Output file base name for HTML help builder. Default is ``'pydoc'``. +.. _latex-options: + Options for LaTeX output ------------------------ diff --git a/doc/contents.rst b/doc/contents.rst index 9336e51e1..6c463f492 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -6,16 +6,16 @@ Sphinx documentation contents .. toctree:: :maxdepth: 1 - intro.rst - concepts.rst - rest.rst - markup/index.rst - builders.rst - config.rst - templating.rst - extensions.rst + intro + concepts + rest + markup/index + builders + config + templating + extensions - glossary.rst + glossary Indices and tables diff --git a/doc/ext.py b/doc/ext.py index 581ea476a..460f1da28 100644 --- a/doc/ext.py +++ b/doc/ext.py @@ -1,4 +1,38 @@ +# -*- coding: utf-8 -*- +""" + ext.py -- Sphinx extension for the Sphinx documentation + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +import re + +from sphinx import addnodes + +dir_sig_re = re.compile(r'\.\. ([^:]+)::(.*)$') + +def parse_directive(sig, signode): + if not sig.startswith('.'): + sig = '.. %s::' % sig + signode += addnodes.desc_name(sig, sig) + return + m = dir_sig_re.match(sig) + if not m: + signode += addnodes.desc_name(sig, sig) + return + name, args = m.groups() + name = '.. %s::' % name + signode += addnodes.desc_name(name, name) + signode += addnodes.desc_classname(args, args) + + +def parse_role(sig, signode): + signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig) + + def setup(app): - app.add_description_unit('directive', 'dir', 'directive') - app.add_description_unit('role', 'role', 'role') + app.add_description_unit('directive', 'dir', 'directive', parse_directive) + app.add_description_unit('role', 'role', 'role', parse_role) app.add_description_unit('confval', 'confval', 'configuration value') diff --git a/doc/ext/api.rst b/doc/ext/appapi.rst index 5d56850f4..5d56850f4 100644 --- a/doc/ext/api.rst +++ b/doc/ext/appapi.rst diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst new file mode 100644 index 000000000..573291c12 --- /dev/null +++ b/doc/ext/builderapi.rst @@ -0,0 +1,24 @@ +Writing new builders +==================== + +.. class:: sphinx.builder.Builder + + This is the base class for all builders. + + These methods are predefined and will be called from the application: + + .. automethod:: load_env + .. automethod:: get_relative_uri + .. automethod:: build_all + .. automethod:: build_specific + .. automethod:: build_update + .. automethod:: build + + These methods must be overridden in concrete builder classes: + + .. automethod:: init + .. automethod:: get_outdated_docs + .. automethod:: get_target_uri + .. automethod:: prepare_writing + .. automethod:: write_doc + .. automethod:: finish diff --git a/doc/extensions.rst b/doc/extensions.rst index 1aa9aa169..00470f769 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -17,7 +17,8 @@ where an extension can register a hook and run specialized code. .. toctree:: - ext/api.rst + ext/appapi + ext/builderapi Builtin Sphinx extensions @@ -28,8 +29,8 @@ These extensions are built in and can be activated by respective entries in the .. toctree:: - ext/autodoc.rst - ext/doctest.rst - ext/refcounting.rst - ext/ifconfig.rst - ext/coverage.rst + ext/autodoc + ext/doctest + ext/refcounting + ext/ifconfig + ext/coverage diff --git a/doc/intro.rst b/doc/intro.rst index 1d6941353..19b65bae8 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -33,8 +33,6 @@ it asks you. Just run :: and answer the questions. -.. XXX environment - Running a build --------------- diff --git a/doc/markup/code.rst b/doc/markup/code.rst index ab1420c2c..bceafb4c0 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -3,6 +3,9 @@ Showing code examples --------------------- +.. index:: pair: code; examples + single: sourcecode + 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. @@ -78,14 +81,24 @@ on line numbers for the individual block:: 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:: +.. directive:: .. literalinclude:: filename + + 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 - .. literalinclude:: example.py + The file name is relative to the current file's path. -The file name is relative to the current file's path. + The directive also supports the ``linenos`` flag option to switch on line + numbers, and a ``language`` option to select a language different from the + current file's standard language. Example with options:: + + .. literalinclude:: example.rb + :language: ruby + :linenos: .. rubric:: Footnotes diff --git a/doc/markup/infounits.rst b/doc/markup/desc.rst index 7360ff2c5..afcd3bf9d 100644 --- a/doc/markup/infounits.rst +++ b/doc/markup/desc.rst @@ -20,7 +20,7 @@ file might start like this:: As you can see, the module-specific markup consists of two directives, the ``module`` directive and the ``moduleauthor`` directive. -.. directive:: module +.. directive:: .. module:: name This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the @@ -38,7 +38,7 @@ As you can see, the module-specific markup consists of two directives, the 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 +.. directive:: .. moduleauthor:: name <email> The ``moduleauthor`` directive, which can appear multiple times, names the authors of the module code, just like ``sectionauthor`` names the author(s) @@ -53,7 +53,7 @@ As you can see, the module-specific markup consists of two directives, the in overview files. -Information units +Description units ----------------- There are a number of directives used to describe specific features provided by @@ -78,7 +78,7 @@ index entries more informative. The directives are: -.. directive:: cfunction +.. directive:: .. cfunction:: type name(signature) Describes a C function. The signature should be given as in C, e.g.:: @@ -90,7 +90,7 @@ The directives are: Note that you don't have to backslash-escape asterisks in the signature, as it is not parsed by the reST inliner. -.. directive:: cmember +.. directive:: .. cmember:: type name Describes a C struct member. Example signature:: @@ -100,7 +100,7 @@ The directives are: 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 +.. directive:: .. cmacro:: name 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 @@ -108,29 +108,29 @@ The directives are: of its use in the Python documentation include :cmacro:`PyObject_HEAD` and :cmacro:`Py_BEGIN_ALLOW_THREADS`. -.. directive:: ctype +.. directive:: .. ctype:: name Describes a C type. The signature should just be the type name. -.. directive:: cvar +.. directive:: .. cvar:: type name Describes a global C variable. The signature should include the type, such as:: .. cvar:: PyObject* PyClass_Type -.. directive:: data +.. directive:: .. data:: name Describes global data in a module, including both variables and values used as "defined constants." Class and object attributes are not documented using this environment. -.. directive:: exception +.. directive:: .. exception:: name Describes an exception class. The signature can, but need not include parentheses with constructor arguments. -.. directive:: function +.. directive:: .. function:: name(signature) Describes a module-level function. The signature should include the parameters, enclosing optional parameters in brackets. Default values can be @@ -148,29 +148,29 @@ The directives are: are modified), side effects, and possible exceptions. A small example may be provided. -.. directive:: class +.. directive:: .. class:: name[(signature)] Describes a class. The signature can include parentheses with parameters which will be shown as the constructor arguments. -.. directive:: attribute +.. directive:: .. attribute:: name 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 +.. directive:: .. method:: name(signature) 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 +.. directive:: .. opcode:: name Describes a Python bytecode instruction (this is not very useful for projects other than Python itself). -.. directive:: cmdoption +.. directive:: .. cmdoption:: name args Describes a command line option or switch. Option argument names should be enclosed in angle brackets. Example:: @@ -179,14 +179,14 @@ The directives are: Run a module as a script. -.. directive:: envvar +.. directive:: .. envvar:: name Describes an environment variable that the documented code uses or defines. There is also a generic version of these directives: -.. directive:: describe +.. directive:: .. describe:: text This directive produces the same formatting as the specific ones explained above but does not create index entries or cross-referencing targets. It is diff --git a/doc/markup/index.rst b/doc/markup/index.rst index 5d9da19cd..1127fa739 100644 --- a/doc/markup/index.rst +++ b/doc/markup/index.rst @@ -1,5 +1,3 @@ -.. XXX missing: glossary - Sphinx Markup Constructs ======================== @@ -8,8 +6,8 @@ markup. This section contains the reference material for these facilities. .. toctree:: - infounits.rst - para.rst - code.rst - inline.rst - misc.rst + desc + para + code + inline + misc diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index d0f52342a..2349bf7ea 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -1,10 +1,9 @@ .. highlight:: rest Inline markup -------------- +============= -As said before, Sphinx uses interpreted text roles to insert semantic markup in -documents. +Sphinx uses interpreted text roles to insert semantic markup into documents. Variable names are an exception, they should be marked simply with ``*var*``. @@ -12,8 +11,38 @@ 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 default role (```content```) has no special meaning by default. You are + free to use it for anything you like. + + +Cross-referencing syntax +------------------------ + +Cross-references are generated by many semantic interpreted text roles. +Basically, you only need to write ``:role:`target```, and a link will be created +to the item named *target* of the type indicated by *role*. The links's text +will be the same as *target*. + +There are some additional facilities, however, 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. + + +Cross-referencing Python objects +-------------------------------- The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found: @@ -64,15 +93,19 @@ 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 +dot, this order is reversed. For example, in the documentation of Python's :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. + +Cross-referencing C constructs +------------------------------ + The following roles create cross-references to C-language constructs if they -are defined in the API documentation: +are defined in the documentation: .. role:: cdata @@ -91,19 +124,33 @@ are defined in the API documentation: The name of a C-language type. -The following roles do possibly create a cross-reference, but do not refer -to objects: +Cross-referencing other items of interest +----------------------------------------- + +The following roles do possibly create a cross-reference, but do not refer to +objects: + +.. role:: envvar + + An environment variable. Index entries are generated. Also generates a link + to the matching :dir:`envvar` directive, if it exists. .. role:: token - The name of a grammar token (used in the reference manual to create links - between production displays). + The name of a grammar token (used to create links between + :dir:`productionlist` directives). .. role:: keyword The name of a keyword in Python. This creates a link to a reference label with that name, if it exists. +.. role:: option + + A command-line option to an executable program. The leading hyphen(s) must + be included. This generates a link to a :dir:`cmdoption` directive, if it + exists. + The following role creates a cross-reference to the term in the glossary: @@ -118,7 +165,37 @@ The following role creates a cross-reference to the term in the glossary: If you use a term that's not explained in a glossary, you'll get a warning during build. ---------- + +Cross-referencing arbitrary locations +------------------------------------- + +To support cross-referencing to arbitrary locations 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 <label-name>```. + + +Other semantic markup +--------------------- The following roles don't do anything special except formatting the text in a different style: @@ -132,10 +209,6 @@ in a different style: 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 @@ -209,11 +282,6 @@ in a different style: 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 @@ -232,10 +300,6 @@ in a different style: 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: @@ -279,33 +343,3 @@ They are set in the build configuration file. 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 <label-name>```. diff --git a/doc/markup/para.rst b/doc/markup/para.rst index 89d6dd05a..e0efe5db9 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -3,6 +3,9 @@ Paragraph-level markup ---------------------- +.. index:: note, warning + pair: changes; in version + These directives create short paragraphs and can be used inside information units as well as normal text: @@ -27,7 +30,7 @@ units as well as normal text: appropriate punctuation. This differs from ``note`` in that it is recommended over ``note`` for information regarding security. -.. directive:: versionadded +.. directive:: .. versionadded:: version 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 @@ -44,7 +47,7 @@ units as well as normal text: 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 +.. directive:: .. versionchanged:: version Similar to ``versionadded``, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.). @@ -71,7 +74,7 @@ units as well as normal text: `GNU tar manual, Basic Tar Format <http://link>`_ Documentation for tar archive files, including GNU tar extensions. -.. directive:: rubric +.. directive:: .. rubric:: title 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. @@ -104,44 +107,69 @@ 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. +.. directive:: .. index:: <entries> + + This directive 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: -For example:: + 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``. - .. index:: - single: execution; context - module: __main__ - module: sys - triple: module; search; path + For index directives containing only "single" entries, there is a shorthand + notation:: -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). + .. index:: BNF, grammar, syntax, notation -The possible entry types are: + This creates four index entries. -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:: +Glossary +-------- - .. index:: BNF, grammar, syntax, notation +.. directive:: glossary + + This directive must contain a reST definition list with terms and + definitions. The definitions will then be referencable with the :role:`term` + role. Example:: + + .. 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. -This creates four index entries. Grammar production displays @@ -170,7 +198,6 @@ the definition of the symbol. There is this directive: 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:: |