diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst index 0eea963a4..7f81d4f68 100644 --- a/doc/usage/domains/index.rst +++ b/doc/usage/domains/index.rst @@ -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 - - 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 - - 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 --------------------- diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst new file mode 100644 index 000000000..add29be0f --- /dev/null +++ b/doc/usage/domains/standard.rst @@ -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 + + 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 + + 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.