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. 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.
Thanks for your interesting insight in your projects.
I'm using org-mode profoundly since 2015 for a lot of my daily note taking routines. Additionally, I've started two years ago to work some of my readmes/tutorials with org-mode. It provides a fantastic way of helping to write, where I find it much more graceful than RST (or Markdown at all).
One of the reason of change to org-mode, however, was its excellent code blocks and noweb-like feature - as you told residing in org-babel.
However, that is not what org-mode was buying for me, but the sheer extensibility and that you can use it now everywhere (e.g. for static page builder like Jekyll or wiki-pages based on Gollum).
I recommend everyone to peek at the excellent Spacemacs project, https://www.spacemacs.org, for an org-mode experience out-of-the-box.
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. 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