Sphinx Showterm¶
A Sphinx extension to embed termshows from showterm.io into your Sphinx documentation.
The source for sphinxcontrib-showterm is hosted on GitHub: tbielawa/sphinxcontrib-showterm
Example¶
Below is the example termshow from the showterm.io homepage. It is embedded in this document using the
showterm
extension:
Installation¶
You will need to have the python module sphinxcontrib-showterm
installed to use this extension. This is available via PyPi:
$ pip install sphinxcontrib-showterm
And inside of your conf.py
file you will add
'sphinxcontrib.showterm'
to the extensions
list:
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.showterm']
Are you using a site like readthedocs to
host your documentation? You will need to fill in a value for the
Requirements file
option under the Admin - Advanced
Settings menu. This file needs to list any modules you need pip
installed prior to building your documentation.
For example, this docsite is rather simple. It
only requires the showterm
extension to build the
documentation successfully. In readthedocs this project is
configured to use a file called doc-requirements.txt. The
contents of which is displayed below:
sphinxcontrib-showterm
Usage¶
-
.. showterm::
The
showterm
directive requires one argument:showterm_id
, the ID of your termshow.For example, the example termshow on the showterm.io homepage is
7b5f8d42ba021511e627e
. We could embed it in a reST document like this:.. showterm:: 7b5f8d42ba021511e627e
The showterm.io service can also be ran privately. If you’re running your own showterm server you can set the showterm domain with the
showtermurl
flag option. For example, if your showterm domain werehttps://showterm.example.com
:.. showterm:: 7b5f8d42ba021511e627e :showtermurl: https://showterm.example.com
Note
Trailing slashes in the
showtermurl
are insignificant. All URLs are normalized prior to document rendering.It’s OK if we’re not running the showterm service at the root location of our domain. We can include the location in the option argument too. For example, if our showterm service is running under
https://utils.example.com/showterm/
:.. showterm:: 7b5f8d42ba021511e627e :showtermurl: https://utils.example.com/showterm/
Limited control over the presentation of the termshow is enabled via the
width
andheight
flag options. The default values for these options are 640px and 480px respectively.Acceptable values for the
width
andheight
options are specified as either an exact pixel value (with thepx
unit), or as a percentage (with the%
unit). Spaces count, so do not include them between the number and the unit:Good:
1337px
33%
Bad:
100 px
100
100 %
Below is an example where we explicitly set the
width
andheight
parameters to higher resolution values:.. showterm:: 7b5f8d42ba021511e627e :width: 1080px :height: 720px
The speed of the termshow can also be configured by using the
speed
option flag. Acceptable values include:slow
- default (equivalent to real-time speed)fast
- 2x the original speedstop
- stopped
Below is an example where we embed the termshow but do not run it yet. This termshow is stopped and awaiting the client to start it:
.. showterm:: 7b5f8d42ba021511e627e :speed: stop
Attempting to use any other value for the
speed
option will result in a compilation error like the following:$ make html sphinx-build -b html -d build/doctrees source build/html Running Sphinx v1.1.3 loading pickled environment... done building [html]: targets for 1 source files that are out of date ... /home/tbielawa/Projects/sphinxcontrib-showterm/docsite/source/index.rst:27: ERROR: Error in "showterm" directive: invalid option value: (option: "speed"; value: 'derp') "derp" unknown; choose from "slow", "fast", or "stop". .. showterm:: 7b5f8d42ba021511e627e :speed: derp /home/tbielawa/Projects/sphinxcontrib-showterm/docsite/source/index.rst:107: WARNING: Literal block expected; none found.
Configuration Settings (conf.py
)¶
You can set termshow display default configuration parameters in your
conf.py
file. None of these settings need to be defined in your
conf.py
file explicitly. Below is a list of supported settings and
their defaults if not overridden.
Parameter | Description | Default |
---|---|---|
showtermurl |
Base url to termshows. Change if you run your own showterm server | https://showterm.io |
showtermwidth |
Default termshow width | 640px |
showtermheight |
Default termshow height | 480px |
showtermspeed |
Default termshow speed. Acceptable values are: slow , fast , and stop . |
stop |
Features Coming Soon¶
Check out all open issues/RFEs on the GitHub issue tracker: tbielawa/sphinxcontrib-showterm