Do What I Mean

Documentation

Table of Contents

Clearly, reStructured Text (reST) is the most Pythonic documentation format. And Sphinx is the generator to go with it.

However, for most use cases, I find reST far too complicated and I prefer Orgmode (and sometimes Markdown) for documentation.

On occasion I use an Online Syntax Highlighter to format source code.

1 Nikola

I sometimes blog with Markdown-files and publish it with static site generator Nikola. While writing I can check the live result with the nikola auto command.

One of the lesser known features of Nikola are shortcodes: simple snippets that you can use throughout your blog. They come in the varieties built-in, community-provided, and home-made. The simplest way to roll your own is by using templates in the shortcodes directory. For example, I have defined a shortcodes/attention.tmpl that gives me {{% attention %}} whenever I want it.

©2019 otech-nl