About this documentation¶
This documentation is generated using Sphinx, using the rtd theme.
Eventually we might even host it at Read the Docs, but currently
someone (usually Ben) generates the static HTML, and then we host it
on GH pages. Since it’s all just reStructured text files in the
docs/ subdirectory, it’s easy for others to contribute.
To generate these docs, you’ll need a few python packages, something like:
pip install sphinx sphinx-autobuild sphinx_rtd_theme
The docs are generated from the reStructured text (
docs/ subdirectory in the Extempore source distribution.
You can edit those files and build the documentation locally if you’ve
got all the Sphinx stuff on your box, just run:
sphinx-autobuild . _build
To actually build the docs to host somewhere, just:
docs/ subdirectory, then take the generated output from
_build/html and dump it on a webserver somewhere—it’s a
self-contained static site.
Currently, we’re hosting it on GitHub pages through the Extempore
repo, in a special
The xtlang lexer has been accepted into Pygments (for proper syntax highlighting of xtlang code) but it hasn’t landed in a stable release yet. If you want to use it, you can get it from bitbucket.
If you find problems, or can think of improvements, fork away on GH, edit the documentation source files and submit a pull request—we’d love these docs to become a real community effort. There will probably be a few broken links and other little things like that, so no pull request is too small to be appreciated :)
If you’ve got questions, or want to bounce around some ideas for improvements before you go ahead and make big changes then get in touch on the mailing list.
ReStructured text cheat sheet¶
Since these docs use Sphinx, their ReStructured text docs are the best place to look, but here are a few quick reminders about the formatting of these doc files.
Section headings are underlined, where the “level” of the heading is determined by the character used for the underline like so:
Section heading =============== Subsection heading ------------------ Subsubsection heading ^^^^^^^^^^^^^^^^^^^^^ Paragraph heading """""""""""""""""
For Extempore code blocks, use the
source-code directive, then
indent the code block:
.. source-code:: extempore (printf "foo")