Sphinx awesome sampdirective

This Sphinx extension provides a new directive samp which works much like the interpreted text role samp. This extension can be used to markup placeholder variables in code blocks.

Installation

Install the extension:

pip install sphinxawesome-sampdirective

This Sphinx extension should work with Python versions newer than 3.6 and recent Sphinx releases.

Configuration

To enable this extension in Sphinx, add it to the list of extensions in the Sphinx configuration file conf.py:

extensions = ["sphinxawesome.sampdirective"]

Use

Include the directive in your documents:

.. samp::

   $ echo {USERNAME}

USERNAME will become an emphasized node. In many outputs, it will be rendered as USERNAME. For example, in HTML, the above example will be rendered as:

<pre>
    <span class="gp">$</span> echo <em class="var">USERNAME</em>
</pre>

You can then control the style of the emphasized element with the .var class in CSS. If the code block begins with a prompt character (#, $, or ~), they will be marked up as well. The style for the prompt character is provided by the pygments syntax highlighting module.

The Sphinx awesome theme includes styling for the samp directive by default.

Caveat

This extension does not provide full syntax highlighting. It is currently not possible to have code blocks with both markup and syntax highlighting. You have to choose between the following:

• If you need to render markup, for example links, or bold or italic text, choose the parsed-literal directive.
• If you just want to highlight a placeholder variable, use the samp directive provided by this extension.
• If you need full syntax highlighting, use the code-block directive.