MkDocs semiliterate Plugin
This plugin for MkDocs is an extension of Allison Thackston’s excellent mkdocs-simple-plugin. It allows you to include content from one file into another (via {! ... !}
syntax), using exactly the same extraction specification that the simple
plugin already uses for identifying documentation in source files.
The current version of mkdocs-semiliterate is 0.8.3.
It is built on mkdocs-simple-plugin v3.2.0.
Rationale
Time and trends have not validated Knuth’s original vision of “literate programming” as a mainstream practice. Nevertheless, there remain significant advantages to incorporating all documentation, including user-guide-style narrative, into the source code for a project. These advantages include ease of maintenance and synchronization of code and documentation, and opportunities to make the ensemble of your code and documentation more DRY. Thus, it’s worth using a “semiliterate” programming style, in which
- code is arranged as dictated by best software engineering practices
- documentation is co-located in the same files next to the implementing code
- and tools are provided for extracting and assembling that documentation into readable form.
The simple
plugin goes a long way toward creating a semiliterate programming environment. However, in creating narrative documentation, it’s very useful to be able to quote or incorporate content — whether that be documentation blocks or code examples or code that itself serves as documentation to avoid repeating information — from one file into another. To satisfy that need, this semiliterate
plugin extends (i.e, literally inherits from) the simple
plugin and adds a syntax for such inclusion.
With a few other small ease-of-use tweaks (documented in the Usage section), this extended plugin aims to produce a lightweight but comprehensive semiliterate programming environment. This documentation site is, of course, produced by MkDocs using the semiliterate plugin.
Installation
The mkdocs-semiliterate package which provides the semiliterate
plugin for MkDocs is available via PyPI:
python3 -m pip install mkdocs-semiliterate
or of course if your pip
is already set up to use a Python 3.5 (or later) installation, just
pip install mkdocs-semiliterate
License and Acknowledgments
This software is licensed under Apache 2.0. Icons8 provided the icon.