Skip to content

Literate Programming ¤

The "LP" feature of docutools allows to

  • embed executable parametrizable code within markdown sources and

  • insert into the rendering result the evaluated output, before html build time, including possibly

    • javascript helper libraries
    • javascript code
    • styles.

This is done through a plugin, with an on_markdown hook, i.e. before html is generated.

Motivation¤

The main benefit of the LP plugin is to keep documentation in sync with the system you are documenting.
And vice versa.

Note

The plugin is heavily inspired by emacs' org-babel.

Feature Highlights¤

  • Concise Syntax: Does not distract when reading source

  • Stateless and Stateful Evaluation, using tmux

Means you can inspect and even change what's going on, before, after and during page evaluation.

Anything set within the tmux session (e.g. environ, variables) is available in later mkdocs build runs, except when you decide to kill the session.

  • Assertions: You can assert on the evaluation result, i.e. you can turn the code blocks into a functional test suite, documented through your markdown around the blocks.

  • Various Output Formats

  • Various Builtin Evaluation Plugins. Extendable with your own.

  • Caching: Results are cached and only re-evaluated when source changes. You can edit the markdown around, w/o triggering possibly expensive evaluation runs. By deciding to commit the cache files you can opt to prevent CI from executing code which is only runnable on certain machines (e.g. where you have your cloud infra keys)

  • Debugging: Execution can be halted and context inspected

  • Full Terminal Color Support: Colorized terminal output via xterm.js

  • Async Results Fetching: Big evaluation results may be fetched only on demand, e.g. on click on otherwise non expanded "Output" tabs

  • Coverage Backrefs: Dynamic coverage contexts, optionally with backrefs to the markdown source line of the LP block, triggering the evaluation

Here the list of parameters for the default mode: Evaluation in a (bash) shell.

Usage: lcd-lp within your mkdocs.yml file, section plugins.

Requirements¤

  • tmux (sessions for the default evaluation mode: bash)
  • ripgrep (code searching)
  • fd (file finding)

Security¤

Documentation is source code.

Documentation Building Runs Arbitrary Code

Consequence: Treat other people's documentation sources with the same care than you treat e.g. their test code: Untrusted sources should be built only within proper sandboxes!

Alternatives¤

For rather code centric documentation have a look at these

  • Pheasant
    • Auto generation of outputs for a fenced code block or inline code in Markdown source using Jupyter client. The code language is not restricted to Python.
    • Auto numbering of headers, figures, tables, and etc. Numbered objects can be linked from other Markdown sources.
  • https://pypi.org/project/mkdocs-jupyter/
  • There are other notebook converters as well