mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Update documentation, add more content.
This commit is contained in:
Georg Brandl
parent
14da7605e4
commit
ca528099f6
@ -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``.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
38
doc/ext.py
38
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')
|
||||
|
||||
24
doc/ext/builderapi.rst
Normal file
24
doc/ext/builderapi.rst
Normal file
@ -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
|
||||
@ -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
|
||||
|
||||
@ -33,8 +33,6 @@ it asks you. Just run ::
|
||||
|
||||
and answer the questions.
|
||||
|
||||
.. XXX environment
|
||||
|
||||
|
||||
Running a build
|
||||
---------------
|
||||
|
||||
@ -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
|
||||
|
||||
.. literalinclude:: example.py
|
||||
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::
|
||||
|
||||
The file name is relative to the current file's path.
|
||||
.. literalinclude:: example.py
|
||||
|
||||
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
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -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>```.
|
||||
|
||||
@ -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>
|
||||
|
||||
For example::
|
||||
This directive contains one or more index entries. Each entry consists of a
|
||||
type and a value, separated by a colon.
|
||||
|
||||
.. index::
|
||||
single: execution; context
|
||||
module: __main__
|
||||
module: sys
|
||||
triple: module; search; path
|
||||
For example::
|
||||
|
||||
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::
|
||||
single: execution; context
|
||||
module: __main__
|
||||
module: sys
|
||||
triple: module; search; path
|
||||
|
||||
The possible entry types are:
|
||||
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).
|
||||
|
||||
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``.
|
||||
The possible entry types are:
|
||||
|
||||
For index directives containing only "single" entries, there is a shorthand
|
||||
notation::
|
||||
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:: BNF, grammar, syntax, notation
|
||||
For index directives containing only "single" entries, there is a shorthand
|
||||
notation::
|
||||
|
||||
.. index:: BNF, grammar, syntax, notation
|
||||
|
||||
This creates four index entries.
|
||||
|
||||
|
||||
Glossary
|
||||
--------
|
||||
|
||||
.. 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::
|
||||
|
||||
Loading…
Reference in New Issue
Block a user