Showcasing¶

In developing the documentation for this theme, it became apparent that we needed a way to avoid duplicating code samples to show both document source syntax and HTML rendering of the document source code.

Introducing the rst-example and myst-example directives! To use these directives, enable the "sphinx_immaterial.theme_result" extension.

extensions = [
    "sphinx_immaterial.theme_result",
]

.. rst-example::

    Some Title
    ==========

    Some content that ends in a page break.

    ----

<div class="results">

```md
# Some Title

And a page break.

----
```

<div class="result">

# Some Title

And a page break.

----

</div></div>

.. raw:: html

    <div class="results">

.. code-block:: rst

    Some Title
    ==========

    And a page break.

    ----

.. raw:: html

    <div class="result">

Some Title
==========

And a page break.

----

.. raw:: html

    </div></div>

.. rst-example::¶

This directive takes reStructuredText code as content and generates

1. A code block to showcase the reStructuredText syntax

2. A decorated rendering of the given reStructuredText content

This directive also takes 1 optional argument to be used as the caption for the generated code block.

.. rst-example:: A showcase caption

    This example is actually *recursive*!

A showcase caption¶

This example is actually *recursive*!

This example is actually recursive!

:output-prefix:¶

This option allows separating the generated code block and rendered result with text for conciseness. If no value is given, then the default phrase is used “Which renders the following content:”

Using the default value Using a custom value

.. rst-example::
    :output-prefix:

    The directive content to showcase.

The directive content to showcase.

Which renders the following content:

The directive content to showcase.

.. rst-example::
    :output-prefix: The above code renders the following result:

    The directive content to showcase.

The directive content to showcase.

The above code renders the following result:

The directive content to showcase.

:class:¶

This option allows specifying a list of space-separated CSS classes.

Fun fact: This option was used to demonstrate using a self-hosted font.

.. rst-example::
    :class: custom-font-example

    This text is just an **example**.
    *Notice* the font family used is different (monospaced) in the code snippet.

This text is just an **example**.
*Notice* the font family used is different (monospaced) in the code snippet.

This text is just an example. Notice the font family used is different (monospaced) in the code snippet.

Example

This option was also used to add padding to this page’s recursive examples’ rendered output.

.. rst-example::
    :class: recursive-rst-example

/* style for recursive rst-example rendering */
div.results.recursive-rst-example > div.result {
  padding-bottom: 1em;
}

:name:¶

This option allows specifying an id to use for cross-referencing. Ultimately, it adds an id attribute for the rendered HTML element.

.. rst-example::
    :name: ref-this-example

    A :ref:`cross-reference link to this example <ref-this-example>`.

A :ref:`cross-reference link to this example <ref-this-example>`.

A cross-reference link to this example.

.. myst-example::¶

This is really just an alias of the rst-example for readability in markdown document sources. It is meant to be used with Markdown code as content instead of reStructuredText.

Warning

Markdown syntax is really only parsed when this directive is used from within a Markdown file. If this directive is invoked within a reStructuredText file, then the given content is parsed as reStructuredText syntax.

Since this page’s source code is written in reStructuredText, no markdown examples can be showcased here properly. See MyST MarkDown Typography as those example snippets all use this directive.

All options from the rst-example directive are also available in this directive. The optional directive argument is also available with this directive. Please refer to the documented directive options and optional argument above.

An example (using all directive options and an argument as documented above) written in MyST syntax would look like the following:

```{myst-example} A showcase caption
:output-prefix: Which renders the following content:
:class: custom-css-class
:name: reference-this-example

This directive __content__ will be
rendered as a `code snippet` with
**decorated** results.
```