1.20. Semantic Descriptions and References

Sphinx also has much more powerful semantic referencing capabilities, which knows all about software development concepts.

Say you’re creating a CLI application. You can define the name of the executable application program and its option and envvar quite easily.

.. program::
.. option::
.. envvar::

For more details, see program, option and envvar directive.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
.. _dlapp:

.. rubric:: Dreamland

A fantasy command-line interface application.

.. program:: dlapp

.. option:: -f, --force

   Force the operation.

.. option:: -i <regex>, --ignore <regex>

   Ignore things that match a specific pattern.

.. envvar:: DLAPPRC

   Set location of resources.
Which gives

Dreamland

A fantasy command-line interface application.

-f, --force

Force the operation.

-i <regex>, --ignore <regex>

Ignore things that match a specific pattern.

DLAPPRC

Set location of resources.

That can now also be referenced quite simply.

:program:
:option:
:envvar:

For more details, see program, option and envvar role.

The example
1
2
3
4
5
.. seealso:: Working with :ref:`dlapp` (:program:`dlapp`):

   * forcing with :option:`dlapp --force`
   * ignoring with :option:`dlapp -i`
   * defaults with :envvar:`DLAPPRC`
Which gives

See also

Working with Dreamland (dlapp):

Sphinx includes a large number of these semantic types, including: