mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Split out the Standard domain
This commit is contained in:
Adam Turner
parent
de3266ab25
commit
c8b2191059
@ -171,100 +171,6 @@ In short:
|
||||
refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
|
||||
|
||||
|
||||
.. _domains-std:
|
||||
|
||||
The Standard Domain
|
||||
-------------------
|
||||
|
||||
The so-called "standard" domain collects all markup that doesn't warrant a
|
||||
domain of its own. Its directives and roles are not prefixed with a domain
|
||||
name.
|
||||
|
||||
The standard domain is also where custom object descriptions, added using the
|
||||
:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.
|
||||
|
||||
There is a set of directives allowing documenting command-line programs:
|
||||
|
||||
.. rst:directive:: .. option:: name args, name args, ...
|
||||
|
||||
Describes a command line argument or switch. Option argument names should
|
||||
be enclosed in angle brackets. Examples::
|
||||
|
||||
.. option:: dest_dir
|
||||
|
||||
Destination directory.
|
||||
|
||||
.. option:: -m <module>, --module <module>
|
||||
|
||||
Run a module as a script.
|
||||
|
||||
The directive will create cross-reference targets for the given options,
|
||||
referenceable by :rst:role:`option` (in the example case, you'd use something
|
||||
like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
|
||||
|
||||
.. versionchanged:: 5.3
|
||||
|
||||
One can cross-reference including an option value: ``:option:`--module=foobar```,
|
||||
,``:option:`--module[=foobar]``` or ``:option:`--module foobar```.
|
||||
|
||||
Use :confval:`option_emphasise_placeholders` for parsing of
|
||||
"variable part" of a literal text (similarly to the :rst:role:`samp` role).
|
||||
|
||||
``cmdoption`` directive is a deprecated alias for the ``option`` directive.
|
||||
|
||||
.. rst:directive:: .. envvar:: name
|
||||
|
||||
Describes an environment variable that the documented code or program uses
|
||||
or defines. Referenceable by :rst:role:`envvar`.
|
||||
|
||||
.. rst:directive:: .. program:: name
|
||||
|
||||
Like :rst:dir:`py:currentmodule`, this directive produces no output.
|
||||
Instead, it serves to notify Sphinx that all following :rst:dir:`option`
|
||||
directives document options for the program called *name*.
|
||||
|
||||
If you use :rst:dir:`program`, you have to qualify the references in your
|
||||
:rst:role:`option` roles by the program name, so if you have the following
|
||||
situation ::
|
||||
|
||||
.. program:: rm
|
||||
|
||||
.. option:: -r
|
||||
|
||||
Work recursively.
|
||||
|
||||
.. program:: svn
|
||||
|
||||
.. option:: -r <revision>
|
||||
|
||||
Specify the revision to work upon.
|
||||
|
||||
then ``:option:`rm -r``` would refer to the first option, while
|
||||
``:option:`svn -r``` would refer to the second one.
|
||||
|
||||
If ``None`` is passed to the argument, the directive will reset the
|
||||
current program name.
|
||||
|
||||
The program name may contain spaces (in case you want to document
|
||||
subcommands like ``svn add`` and ``svn commit`` separately).
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
There is also a very generic object description directive, which is not tied to
|
||||
any domain:
|
||||
|
||||
.. rst:directive:: .. describe:: text
|
||||
.. object:: text
|
||||
|
||||
This directive produces the same formatting as the specific ones provided by
|
||||
domains, but does not create index entries or cross-referencing targets.
|
||||
Example::
|
||||
|
||||
.. describe:: PAPER
|
||||
|
||||
You can set this variable to select a paper size.
|
||||
|
||||
|
||||
The JavaScript Domain
|
||||
---------------------
|
||||
|
||||
|
||||
94
doc/usage/domains/standard.rst
Normal file
94
doc/usage/domains/standard.rst
Normal file
@ -0,0 +1,94 @@
|
||||
.. highlight:: rst
|
||||
|
||||
.. _domains-std:
|
||||
|
||||
The Standard Domain
|
||||
-------------------
|
||||
|
||||
The so-called "standard" domain collects all markup that doesn't warrant a
|
||||
domain of its own. Its directives and roles are not prefixed with a domain
|
||||
name.
|
||||
|
||||
The standard domain is also where custom object descriptions, added using the
|
||||
:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.
|
||||
|
||||
There is a set of directives allowing documenting command-line programs:
|
||||
|
||||
.. rst:directive:: .. option:: name args, name args, ...
|
||||
|
||||
Describes a command line argument or switch. Option argument names should
|
||||
be enclosed in angle brackets. Examples::
|
||||
|
||||
.. option:: dest_dir
|
||||
|
||||
Destination directory.
|
||||
|
||||
.. option:: -m <module>, --module <module>
|
||||
|
||||
Run a module as a script.
|
||||
|
||||
The directive will create cross-reference targets for the given options,
|
||||
referenceable by :rst:role:`option` (in the example case, you'd use something
|
||||
like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
|
||||
|
||||
.. versionchanged:: 5.3
|
||||
|
||||
One can cross-reference including an option value: ``:option:`--module=foobar```,
|
||||
,``:option:`--module[=foobar]``` or ``:option:`--module foobar```.
|
||||
|
||||
Use :confval:`option_emphasise_placeholders` for parsing of
|
||||
"variable part" of a literal text (similarly to the :rst:role:`samp` role).
|
||||
|
||||
``cmdoption`` directive is a deprecated alias for the ``option`` directive.
|
||||
|
||||
.. rst:directive:: .. envvar:: name
|
||||
|
||||
Describes an environment variable that the documented code or program uses
|
||||
or defines. Referenceable by :rst:role:`envvar`.
|
||||
|
||||
.. rst:directive:: .. program:: name
|
||||
|
||||
Like :rst:dir:`py:currentmodule`, this directive produces no output.
|
||||
Instead, it serves to notify Sphinx that all following :rst:dir:`option`
|
||||
directives document options for the program called *name*.
|
||||
|
||||
If you use :rst:dir:`program`, you have to qualify the references in your
|
||||
:rst:role:`option` roles by the program name, so if you have the following
|
||||
situation ::
|
||||
|
||||
.. program:: rm
|
||||
|
||||
.. option:: -r
|
||||
|
||||
Work recursively.
|
||||
|
||||
.. program:: svn
|
||||
|
||||
.. option:: -r <revision>
|
||||
|
||||
Specify the revision to work upon.
|
||||
|
||||
then ``:option:`rm -r``` would refer to the first option, while
|
||||
``:option:`svn -r``` would refer to the second one.
|
||||
|
||||
If ``None`` is passed to the argument, the directive will reset the
|
||||
current program name.
|
||||
|
||||
The program name may contain spaces (in case you want to document
|
||||
subcommands like ``svn add`` and ``svn commit`` separately).
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
There is also a very generic object description directive, which is not tied to
|
||||
any domain:
|
||||
|
||||
.. rst:directive:: .. describe:: text
|
||||
.. object:: text
|
||||
|
||||
This directive produces the same formatting as the specific ones provided by
|
||||
domains, but does not create index entries or cross-referencing targets.
|
||||
Example::
|
||||
|
||||
.. describe:: PAPER
|
||||
|
||||
You can set this variable to select a paper size.
|
||||
Loading…
Reference in New Issue
Block a user