For my use cases, I care about writing software documentation, and also rendering Python API documentation - the special "docstring" documentation comments within Python source code. See PEP 257 - Docstring conventions for Python style guidelines. I currently use epydoc for this, which supports a range of markup languages including its own epytext markup language. Another potential choice is Sphinx, which currently only supports the reStructuredText markup language.
For larger documents including my PhD Thesis and scientific papers, I like to use LaTeX. This is really powerful for mathematical markup, but also makes cross-references between Figures, Tables, and document sections pretty easy. It is far more popular in Mathematics and Physics than it is in Biology.
And for online repository and wiki hosting BitBucket supports several markup languages, while GitHub supports even more markup languages,
| Language/tool | epydoc | Sphinx | GitHub | BitBucket |
| epytext | Yes | No | No | No |
| reStructuredText | Yes | Yes | Yes | Yes |
| MarkDown | No | No | Yes | Yes |
| textile | No | No | Yes | Yes |
| creole | No | No | Yes | Yes |
| LaTeX | No | No | No | No |
MarkDown would be a nice choice, but even if we ignore Sphinx, it looks like for a Python project, the only sensible choice in terms of broad tool support is currently reStructuredText.
I have spent a great deal on evaluating markup languages for Biostar. Once one gets into the nitty gritty details the flaws of each approach become more and more apparent.
ReplyDeleteReST is unfortunately a gigantic beast of a software that as far as I could tell feels grossly overenigneered, it is a large python package. I failed in my attempts to add or modify it. Moreover the markup can be very annoying, for example making links etc
Markdown is much simpler for example the markdown2.py library is just one file. There are some design flaws, such as the underscore indicating italics - but most github flavors override that.
In addition its greatest advantage is that it does (optionally) allow HTML to be embedded in the document. This I found to be a lifesaver. If one ever wants to create a document that goes beyond documenting what a python code does they run into sever limitation where dropping to HTML for a paragraph say set up a table, insert a javascript, add an eclosing DIV make life orders of magnitude easier.
In addition Mardown has many visual editors.
Have you thought about the html output rendered by ipython notebook files? if you want to publish the .ipynb files directly, that is always super nice to let others recreate your research.
ReplyDeleteIn the first case I am interested in producing nice API docs, which means a markup language I can use I'm my docstrings.
Delete