mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
84 lines
3.4 KiB
ReStructuredText
84 lines
3.4 KiB
ReStructuredText
.. _glossary:
|
|
|
|
Glossary
|
|
========
|
|
|
|
.. glossary::
|
|
|
|
builder
|
|
A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
|
|
parsed documents and performs an action on them. Normally, builders
|
|
translate the documents to an output format, but it is also possible to
|
|
use the builder builders that e.g. check for broken links in the
|
|
documentation, or build coverage information.
|
|
|
|
See :ref:`builders` for an overview over Sphinx's built-in builders.
|
|
|
|
configuration directory
|
|
The directory containing :file:`conf.py`. By default, this is the same as
|
|
the :term:`source directory`, but can be set differently with the **-c**
|
|
command-line option.
|
|
|
|
directive
|
|
A reStructuredText markup element that allows marking a block of content
|
|
with special meaning. Directives are supplied not only by docutils, but
|
|
Sphinx and custom extensions can add their own. The basic directive
|
|
syntax looks like this:
|
|
|
|
.. sourcecode:: rst
|
|
|
|
.. directivename:: argument ...
|
|
:option: value
|
|
|
|
Content of the directive.
|
|
|
|
See :ref:`directives` for more information.
|
|
|
|
document name
|
|
Since 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: :dfn:`document names` are always
|
|
relative to the :term:`source directory`, the extension is stripped, and
|
|
path separators are converted to slashes. All values, parameters and such
|
|
referring to "documents" expect such document names.
|
|
|
|
Examples for document names are ``index``, ``library/zipfile``, or
|
|
``reference/datamodel/types``. Note that there is no leading or trailing
|
|
slash.
|
|
|
|
domain
|
|
A domain is a collection of markup (reStructuredText :term:`directive`\ s
|
|
and :term:`role`\ s) to describe and link to :term:`object`\ s belonging
|
|
together, e.g. elements of a programming language. Directive and role
|
|
names in a domain have names like ``domain:name``, e.g. ``py:function``.
|
|
|
|
Having domains means that there are no naming problems when one set of
|
|
documentation wants to refer to e.g. C++ and Python classes. It also
|
|
means that extensions that support the documentation of whole new
|
|
languages are much easier to write. For more information about domains,
|
|
see the chapter :ref:`domains`.
|
|
|
|
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.
|
|
|
|
master document
|
|
The document that contains the root :rst:dir:`toctree` directive.
|
|
|
|
object
|
|
The basic building block of Sphinx documentation. Every "object
|
|
directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a
|
|
block; and most objects can be cross-referenced to.
|
|
|
|
role
|
|
A reStructuredText markup element that allows marking a piece of text.
|
|
Like directives, roles are extensible. The basic syntax looks like this:
|
|
``:rolename:`content```. See :ref:`inlinemarkup` for details.
|
|
|
|
source directory
|
|
The directory which, including its subdirectories, contains all source
|
|
files for one Sphinx project.
|