Adding upstream version 7.3.7.upstream/7.3.7

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.