sphinxawesome-sampdirective 1.0.0

A Sphinx directive for literal blocks with emphasis

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 sphinxawesome theme includes styling for the ..samp:: directive.

Caveat

This extension does not provide full syntax highlighting. It is currently not possible to have code blocks with both markup and syntax highlighting. 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.