diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-06-05 16:20:59 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-06-05 16:20:59 +0000 |
commit | 5de84c9242643f786eff03726286578726d7d390 (patch) | |
tree | 8e8eadab2b786c41d7b8a2cdafbb467588928ad0 /doc/usage/domains/standard.rst | |
parent | Releasing progress-linux version 7.2.6-8~progress7.99u1. (diff) | |
download | sphinx-5de84c9242643f786eff03726286578726d7d390.tar.xz sphinx-5de84c9242643f786eff03726286578726d7d390.zip |
Merging upstream version 7.3.7.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage/domains/standard.rst')
-rw-r--r-- | doc/usage/domains/standard.rst | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst new file mode 100644 index 0000000..59b7e72 --- /dev/null +++ b/doc/usage/domains/standard.rst @@ -0,0 +1,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. |