CommonMark for documentation - a checklist

Hi, I’m writing down all the extension missing/needed to match other markups commonly used documentation systems, I’m considering sphinx, texinfo and secondarily kramdown since they have similar features and they are used quite widely, rust probably would aim to the same featureset.

Key features

  • decent manpage generation, supporting at least some of the manpage features quite well. It is a really welcomed feature.
  • working html generation with support for sections and table of contents/navigation
  • pdf generation is a not fully necessary.

CommonMark to match it needs:

  • table support
  • attribute/extension support (as in kramdown) for inclusion and man metadata and toc.

I already prepared some bindings to use CommonMark-py together with docutils to produce manpage and mainly I miss the extension above to have a full solution to let people leverage sphinx with CommonMark instead of reStructuredText.

You can find some initial work here.

There is an extensive conversation about CommonMark’s suitability as a documentation language on the Rust-lang forum. It covers CommonMark (Markdown), reStructuredText and asciidoc.

I plan to add kramdown attribute support to commonmark-py so that the docutils bridge is complete and would be possible to leverage sphinx easily.