zephyr/doc/documentation/rest_inline.rst

.. _inline:

Inline Markup
*************

Sphinx supports a large number of inline markup elements. The
documentation of the Zephyr OS only requires the use of the inline
markup found here. Additional inline markup can be used as long as it
is supported by Sphinx. Please refer to the `Sphinx Inline Markup`_
documentation for the full list of supported inline markup. Use the
following markup for every instance you encounter unless otherwise
specified.

* Use the 'abbreviation' markup to define an acronym or an initialism.
The abbreviation only needs to be added once per module. Ensure that
any acronym or initialism used in a module has been defined at least
once, otherwise the submission will not be accepted.

   :abbr:`API (Application Program Interface)`

   ``:abbr:`TIA (This Is an Abbreviation)```

* Use the 'command' markup only when the name of a specific command is
used as part of a paragraph for emphasis. Use the ``.. code-block::``
directive to supply full actionable commands as part as a series of
steps.

   :command:`make`

   ``:command:`command```

* Use the 'option' markup to emphasize the name of a command option
with or without its value. This markup is usually employed in
combination with the 'command' markup.

   :option:`-f`
   :option:`--all`
   :option:`-o output.xsl`
   The :command:`pandoc` command can be used without the :option:`-o`
   option, creating an output file with the same name as the source
   but a different extension.

   ``:option:`Option```

* Use the 'file' markup to emphasize a filename or directory. Do not
use the markup inside a code-block but use it inside all notices that
contain files or directories.

   :file:`collaboration.rst` :file:`doc/collaboration/figures`

   ``:file:`filename.ext` :file:`path/or/directory```

* Use the 'guilabel' markup to emphasize the elements in a graphic
user interface within a description. It replaces the use of quotes
when referring to windows' names, button labels, options or single
menu elements. Always follow the marked element with the appropriate
noun.

   In the :guilabel:`Tools` menu.
   Press the :guilabel:`OK` button.
   In the :guilabel:`Settings` window you find the :guilabel:`Hide
   Content` option.

   ``:guilabel:`UI-Label```

* Use the 'menuselection' markup to indicate the navigation through a
menu ending with a selection. Every 'menuselection' element can have
up to two menu steps before the selected item. If more than two steps
are required, it can be combined with a 'guilabel' or with another
'menuselection' element.

   :menuselection:`File --> Save As --> PDF`
   Go to :guilabel:`File` and select :menuselection:`Import --> Data
   Base --> MySQL`.
   Go to :menuselection:`Window --> View` and select :menuselection:`
   Perspective --> Other --> C++`

   ``:menuselection:`1stMenu --> 2ndMenu --> Selection```

* Use the 'makevar' markup to emphasize the name of a Makefile variable
. The markup can include only the name of the variable or the variable
plus its value.

   :makevar:`PLATFORM_CONFIG`
   :makevar:`PLATFORM_CONFIG=basic_atom`

   ``:makevar:`VARIABLE```

* Use the 'envvar' markup to emphasize the name of environment
variables. Just as with 'makevar', the markup can include only for the
name of the variable or the variable plus its value.

   :envvar:`ZEPHYR_BASE`
   :envvar:`QEMU_BIN_PATH=/usr/local/bin`

   ``:envvar:`ENVIRONMENT_VARIABLE```

.. _Sphinx Inline Markup:
   http://sphinx-doc.org/markup/inline.html#inline-markup