GetTheCode plugin for Sphinx
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-getthecodeElse clone the Git repository:
git clone git@github.com:FabriceSalvaire/sphinx-getthecodethen install the plugin using:
python setup.py installUsage
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 availablewill 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>
