lit2md: a literate program converter from code to Markdown

lit2md is a simplistic literate programming (LP) converter. It takes a source code file annotated with special "literate" programming comments, and outputs a markdown file in which the literate programming comments are converted into markdown text, and code is converted into code blocks.

For example, consider the simplistic hello.cc

//] # An example Hello World program.
//]
//] Don't forget headers!
#include <iostream>

//] And now, the rest of the code here:
int main() {
		std::cout << "Hello world" << std::endl;
		exit(0);
}

Running:

lit2md --input=hello.cc --output=hello.cc.md  # enclosed

produces this output.

To see a minimal usage example, check out the self-referential integration repo.

It could be argued that such a converter could be useful in preparing explanatory documents about existing code. Now, a Markdown file is not extremely useful in itself, but in combination with other typesetting software could prove to be interesting for preparing documents with a fancier layout than shown here.

Finally, the program itself, and its test, can be viewed in their literate programming forms.

LP can be done to various levels of sophistication. lit2md does the very basic massaging of source text.

It is not intended to be used as a stand-alone program. Rather it is intended to be used as a front-end to a more sophisticated documentation processor, such as pandoc. An example of use of a similar program is the instructive website for programmable digital logic designers, https://fpgacpu.ca.

• bazel to build.

Everything else is downloaded automatically.

bazel build //...

bazel test //...

bazel run //cmd/lit2md -- --help

• It works with python only,
• It works with Verilog only,
• It outputs HTML only.

I wanted a tad bit more freedom of choice (since I rarely code straight-up Verilog).

Doxygen is great, but its purpose is to provide user documentation. Literate programs are intended to explain the code instead.

• https://fpgacpu.ca/fpga/v2h.py: direct inspiration for this program. I rewrote it in go, because it is then easy to distribute as a small self-contained binary.