1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
.. highlight:: rst
===================
The Standard Domain
===================
.. versionadded:: 1.0
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.
|
