KAkarlicoss·Mar 24, 2020
Not sure about proper documentation, but I've found Org-mode to be quite enjoyable for writing readmes, mainly because of its org-babel [0] (aka executable code blocks) support.
That way you can include/tangle bits of source code and help strings documentation in the readme, avoiding unnecessary duplication.
The results of the evaluation are committed to the repository as well, and it's plaintext, so you don't need Emacs to fix/update the docs -- you can patch up the evaluation results, and the maintainer with Emacs can fix it properly later.
E.g. here [1] I'm reusing the argparse help string in the readme. That makes the source code the primary source of truth.
Another experiment I did was writing readme as an Ipython notebook [2], and then compiling the output to markdown.
That allowed me to link bits of readme straight to the code. E.g
Read the rest
. as an example, each of the 'Features' [3] links straight to the unit test for that specific feature. The downside is that you need to remember to refresh the readme after code changes, otherwise the line numbers break. Perhaps that can be set up automatically as a CI job.
In hindsight through, would have been easier to use org-mode as well to avoid keeping two separate files for the readme.
- [0] https://orgmode.org/worg/org-contrib/babel/intro.html
- [1] https://github.com/karlicoss/rexport/blame/master/README.org...
- [2] https://github.com/karlicoss/cachew/blob/master/README.ipynb
- [2] https://github.com/karlicoss/cachew#features