Glen Whitney
ec9c7e57ce
Also provides semiliterate plugin stub, lays out basic initial documentation for the project, and adds a simple mkdocs.yml file that builds a rudimentary documentation site.
2.0 KiB
MkDocs semiliterate Plugin
This plugin for MkDocs is an extension of Allison Thackston's excellent mkdocs-simple-plugin. It adds {! ... !} syntax for including content from one file into another (and a couple of other small usability tweaks).
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.
*[DRY]: Don't Repeat Yourself -- a coding philosophy of creating a single authoritative location for each piece of information.
The mkdocs-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 -- 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. The documentation site is, of course, produced by MkDocs using the semiliterate plugin.
Installation
To be written.
License
This software is licensed under Apache 2.0.