Skip to main content

Sphinx getthecode extension

Project description

sphinxcontrib-getthecode license sphinxcontrib-getthecode python version

sphinxcontrib-getthecode last version

This plugin implements an enhanced literalinclude directive for the Sphinx Documentation Generator.

For a demo, look at Pyterate.

Authored by Fabrice Salvaire.

Source code is hosted at https://github.com/FabriceSalvaire/sphinx-getthecode

Installation

Using pip:

pip install sphinxcontrib-getthecode

Else clone the Git repository:

git clone git@github.com:FabriceSalvaire/sphinx-getthecode

then install the plugin using:

python setup.py install

Usage

To load the plugin, you have to add it in your conf.py file.

extensions = [
  ...
  'sphinxcontrib.getthecode',
  ]

Directives

This plugin implements a directive getthecode which is equivalent to the literalinclude directive, but it adds a header before the pre element. This header contains the file name and a link to download the file.

.. getthecode:: example.py
    :language: python3
    :hidden: ### optional, add a class highlight-hidden
    :notebook: ### optional, if a example.ipynb is available

will result in:

<div class="getthecode">
    <div class="getthecode-header">
        <ul>
            <li class="getthecode-filename">example.py</li>

            <li class="getthecode-filename-link">
                <a href="../example.py" download="example.py" type="text/x-python" target="_blank" rel="noreferrer noopener">
                    <span> example.py </span>
                </a>
            </li>

            <li class="getthecode-notebook-link">
                <a href="../example.ipynb" download="example.ipynb" type="application/x-ipynb+json" target="_blank" rel="noreferrer noopener">
                    <span> example.ipynb </span>
                </a>
            </li>

            <!-- Added by javascript -->
            <li class="show-code-button" title="Show/Hide the code">
                <i class="fa fa-eye" aria-hidden="true"></i>
                <i class="fa fa-eye-slash" aria-hidden="true" style="display: none;"></i>
            </li>
        </ul>
    </div>

    <div class="highlight-python3 highlight-hidden" style="display: none;">
        <div class="highlight">
            <pre> </pre>
        </div>
    </div>
</div>

You can find in the static directory an example of CSS stylesheet and a Javascript code to show/hide the code.

You can customise the HTML code using the getthecode_header_template configuration variable that contains a Jinja2 template, by default set to:

<div class="getthecode-header">
  <ul>
    <li class="getthecode-filename">{{ filename }}</li>
    <li class="getthecode-filename-link">
      <a href="{{ url }}" download={{ filename }} type="text/x-python" target="_blank" rel="noreferrer noopener"><span>
        {{ filename }}
      </span></a>
    </li>
{% if notebook_url %}
    <li class="getthecode-notebook-link">
      <a href="{{ notebook_url }}" download={{ notebook_filename }} type="application/x-ipynb+json" target="_blank" rel="noreferrer noopener"><span>
        {{ notebook_filename }}
      </span></a>
    </li>
{% endif %}
  </ul>
</div>

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-getthecode-1.2.1.tar.gz (22.1 kB view hashes)

Uploaded Source

Built Distribution

sphinxcontrib_getthecode-1.2.1-py2.py3-none-any.whl (19.2 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page