jsphinx-download directive

Sphinx is a documentation generator. It has many directives, among which the .. literalinclude::, which allows us to include content of a file directly into your documentation.

.. literalinclude:: itself has a :lines: option, which allows us to specify which parts of the code to show. That’s what we use to keep the primary focus on the most important parts of the code, reducing cognitive load for the reader.

Consider the following code example stored in a file _static/py/faker_file_docx_1.py:

import os

# Required imports
from faker import Faker
from faker_file.providers.docx_file import DocxFileProvider

FAKER = Faker()  # Initialize Faker
FAKER.add_provider(DocxFileProvider)  # Register DocxFileProvider

# Generate DOCX file
docx_file = FAKER.docx_file()

# Test things out
print(docx_file)
print(docx_file.data["filename"])
assert os.path.exists(docx_file.data["filename"])

See the following snippet:

.. literalinclude:: _static/py/faker_file_docx_1.py
   :language: python
   :lines: 3-11

The above mentioned snippet will be rendered as follows:

# Required imports
from faker import Faker
from faker_file.providers.docx_file import DocxFileProvider

FAKER = Faker()  # Initialize Faker
FAKER.add_provider(DocxFileProvider)  # Register DocxFileProvider

# Generate DOCX file
docx_file = FAKER.docx_file()

However, we also understand the importance of the broader context. For that we use the :download: directive, which allows us to create a downloadable link to a file (the same file we already included into the documentation using .. literalinclude::). By that we ensure that those interested in the complete code can easily access it.

See the following snippet:

.. container:: jsphinx-download

    *See the full example*
    :download:`here <_static/py/faker_file_docx_1.py>`

The above mentioned snippet will be produce the following HTML:

<p class="jsphinx-download">
  <em>See the full example</em>
  <a class="reference download internal" href="_static/py/faker_file_docx_1.py">
    <span class="pre">here</span>
  </a>
</p>

See the jsphinx-download demo to see how it’s rendered.

This is where jsphinx steps in. Using provided JavaScript, we hook to the links generated by the :download: directive and instead of downloading the content, show it in-line, right in place.

Note, that although .. container:: jsphinx-download technically isn’t strictly required, it wraps our link into an element with jsphinx-download class so that we can safely hook to all underlying download links without a risk to cause unwanted behavior for other places where you might have used :download: directive for other purposes.

Finally, PrismJS syntax highlighter is used to beautify the code and make it look close to the code highlighting of your Sphinx theme of choice.

jsphinx-toggle-emphasis directive

Another popular Sphinx directive is the .. code-block::, which enables us to display code blocks within your documentation.

The .. code-block:: directive itself has a :emphasize-lines: option, which is particularly useful for highlighting specific lines of code within the code block. This helps to draw attention to most important parts of the code and helps the reader to understand the code.

Consider the following example:

.. container:: jsphinx-toggle-emphasis

    .. code-block:: python
        :emphasize-lines: 3,6,8

        from faker import Faker
        # Import the file provider we want to use
        from faker_file.providers.txt_file import TxtFileProvider

        FAKER = Faker()  # Initialise Faker instance
        FAKER.add_provider(TxtFileProvider)  # Register the file provider

        txt_file = FAKER.txt_file()  # Generate a TXT file

See the jsphinx-toggle-emphasis demo to see how it’s rendered.

jsphinx will add a link to each .. container:: jsphinx-toggle-emphasis block for toggling the visibility of non-emphasized elements.

Via CDN (jsDelivr)

To use both the theme and adapter in your HTML:

<!-- CSS for PrismJS Sphinx RTD theme -->
<link href="https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css"
      rel="stylesheet">

<!-- JS for PrismJS Sphinx Adapter -->
<script src="https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/js/download_adapter.js">
</script>

Configuration

To integrate both into your Sphinx project, add the following in your conf.py:

# ************************************************************
# ************************** The theme ***********************
# ************************************************************
html_theme = "sphinx_rtd_theme"

# ************************************************************
# ***************** Additional JS/CSS files ******************
# ************************************************************
html_css_files = [
    # ...
    "https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css",
    # ...
]

html_js_files = [
    # ...
    "https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/js/download_adapter.js",
    # ...
]

A complete configuration example, together with loaded PrismJS and the toolbar with plugins, would look as follows:

prismjs_base = "//cdnjs.cloudflare.com/ajax/libs/prism/1.29.0"

html_css_files = [
    f"{prismjs_base}/themes/prism.min.css",
    f"{prismjs_base}/plugins/toolbar/prism-toolbar.min.css",
    "https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css",
]

html_js_files = [
    f"{prismjs_base}/prism.min.js",
    f"{prismjs_base}/plugins/autoloader/prism-autoloader.min.js",
    f"{prismjs_base}/plugins/toolbar/prism-toolbar.min.js",
    f"{prismjs_base}/plugins/copy-to-clipboard/prism-copy-to-clipboard.min.js",
    "https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/js/download_adapter.js",
]

You can also use other Sphinx themes, such as alabaster, furo, pydata-sphinx-theme, sphinx-book-theme, sphinx-bootstrap-theme, sphinx-material or sphinx-rtd-theme.

Make sure to specify appropriate value (theme key) in html_theme, as follows (pick one):

html_theme = "alabaster"
html_theme = "bootstrap"
html_theme = "furo"
html_theme = "pydata_sphinx_theme"
html_theme = "sphinx_book_theme"
html_theme = "sphinx_material"
html_theme = "sphinx_rtd_theme"

Finally, make sure to specify correct path to the desired theme:

html_css_files = [
    # ...
    f"https://cdn.jsdelivr.net/gh/barseghyanartur/jsphinx/src/css/{html_theme}.css",
]