Domains¶
Added in version 1.0.
Сначала Sphinx был задуман для одного проекта - документации языка Python. Вскоре после этого он стал доступен для всех как инструмент документации, но документация модулей Python осталась глубоко встроенной - самые фундаментальные директивы, такие как «функция»“, которые были разработаны для объектов Python. Поскольку Sphinx стал довольно популярным, возник интерес к его использованию для различных целей: проекты C / C ++, JavaScript или даже разметка reStructuredText (как в этой документации).
Хотя это всегда было возможно, теперь намного проще поддерживать документацию по проектам, использующим разные языки программирования или даже те, которые не поддерживаются основным дистрибутивом Sphinx, предоставляя «домен» для каждой такой цели.
Домен - это набор разметки (reStructuredText:term: „directive“s и: term:“role“ s) для описания и ссылки на: term: „object“ s, принадлежащие вместе, например элементы языка программирования. Имена директив и ролей в домене имеют такие имена, как «домен: имя», например «py:function». Домены также могут предоставлять настраиваемые индексы (например, индекс модуля Python).
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.
This section describes what the domains that are included with Sphinx provide. The domain API is documented as well, in the section Domain API.
Basic Markup¶
Most domains provide a number of object description directives, used to describe specific objects 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.
A domain will typically keep an internal index of all entities to aid
cross-referencing.
Typically it will also add entries in the shown general index.
If you want to suppress the addition of an entry in the shown index, you can
give the directive option flag :no-index-entry:
.
If you want to exclude the object description from the table of contents, you
can give the directive option flag :no-contents-entry:
.
If you want to typeset an object description, without even making it available
for cross-referencing, you can give the directive option flag :no-index:
(which implies :no-index-entry:
).
If you do not want to typeset anything, you can give the directive option flag
:no-typesetting:
. This can for example be used to create only a target and
index entry for later reference.
Though, note that not every directive in every domain may support these
options.
Added in version 3.2: The directive option noindexentry
in the Python, C, C++, and Javascript
domains.
Added in version 5.2.3: The directive option :nocontentsentry:
in the Python, C, C++, Javascript,
and reStructuredText domains.
Added in version 7.2: The directive option no-typesetting
in the Python, C, C++, Javascript,
and reStructuredText domains.
Изменено в версии 7.2:
The directive option
:noindex:
was renamed to:no-index:
.The directive option
:noindexentry:
was renamed to:no-index-entry:
.The directive option
:nocontentsentry:
was renamed to:no-contents-entry:
.
The previous names are retained as aliases, but will be deprecated and removed in a future version of Sphinx.
An example using a Python domain directive:
.. py:function:: spam(eggs)
ham(eggs)
Spam or ham the foo.
This describes the two Python functions spam
and ham
. (Note that when
signatures become too long, you can break them if you add a backslash to lines
that are continued in the next line. Example:
.. py:function:: filterwarnings(action, message='', category=Warning, \
module='', lineno=0, append=False)
:no-index:
(This example also shows how to use the :no-index:
flag.)
The domains also provide roles that link back to these object descriptions. For example, to link to one of the functions described in the example above, you could say
The function :py:func:`spam` does a similar thing.
As you can see, both directive and role names contain the domain name and the directive name.
The directive option :no-typesetting:
can be used to create a target
(and index entry) which can later be referenced
by the roles provided by the domain.
This is particularly useful for literate programming:
.. py:function:: spam(eggs)
:no-typesetting:
.. code::
def spam(eggs):
pass
The function :py:func:`spam` does nothing.
Default Domain
For documentation describing objects from solely one domain, authors will not
have to state again its name at each directive, role, etc… after
having specified a default. This can be done either via the config
value primary_domain
or via this directive:
- .. default-domain:: name¶
Select a new default domain. While the
primary_domain
selects a global default, this only has an effect within the same file.
If no other default is selected, the Python domain (named py
) is the
default one, mostly for compatibility with documentation written for older
versions of Sphinx.
Directives and roles that belong to the default domain can be mentioned without giving the domain name, i.e.
.. function:: pyfunc()
Describes a Python function.
Reference to :func:`pyfunc`.
Cross-referencing syntax¶
For cross-reference roles provided by domains, the same facilities exist as for general cross-references. See Cross-referencing syntax.
In short:
You may supply an explicit title and reference target:
: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.If you prefix the content with
~
, the link text will only be the last component of the target. For example,:py:meth:`~Queue.Queue.get`
will refer toQueue.Queue.get
but only displayget
as the link text.
Built-in domains¶
The following domains are included within Sphinx:
More domains¶
There are several third-party domains available as extensions, including: