As a docs junkie I've got to at least try to make this case! Bear with me...
In praise of Markdown
Generally, I love Markdown. It's far and away the easiest mark-up language, and perfect for wikis and short documents. I suspect Markdown has been selected primarily to make contributions to the project's documentation as easy as possible; a laudable goal. However, its very simplicity means that managing a large trove of technical documentation (such as an API reference) rapidly becomes difficult under MD compared to ReST, and there's several other places where ReST is superior...
Links
When making intra-document links (links between pages or sections within the same repository) there seems little consensus whether to link to the MD source files, or the HTML output files (from whatever generator is employed). Moreover, there seem to be several competing ideas on structuring fragments in the first place (inline HTML for naming fragments, using a single MD source for each fragment and combining the output, etc. etc.).
The major issue here is that MD has no extensible link types and thus can't have "a method link" or "an attribute link". For example, in ReST docs I can use :attr:pin`` to make a link to the pin attribute in the current class wherever that may be in the eventual output (in the same page, another page, etc.).
Personally, this came in extremely handy recently when I decided the picamera API docs were becoming far too long (they were taking nearly 10 seconds to load on a mobile platform) and I split them up by module; nothing terribly complicated was involved because most of the class, attribute, and method links stayed more or less the same.
Docstrings and the command line
MD docs typically aren't entered as inline docstrings in the code. This has the unfortunate side-effect that the documentation isn't (easily) accessible from the command line. For example, a user of picamera can simply do the following on the command line to retrieve the (raw) docs for the PiCamera class constructor, and then the resolution property:
>>> import picamera
>>> camera = picamera.PiCamera()
>>> help(camera)
>>> help(camera.resolution)
This becomes even easier under IPython where instead of wrapping things with help() one can simply append a ? suffix for the same effect. This also ties into Goal 1 of the ReST project: to have a markup language that is readable both raw and cooked. I think MD is equally readable raw except when it dives into inline HTML to achieve more complex things (admonitions like hints and warnings, and complex tables layouts).
Still, I will be content if I have at least persuaded you of the need for inline docstrings (whether in MD or ReST) to permit easy command line usage (incidentally, this also allows usage in things like IPython notebook's popup help).
Offline access
While offline access is becoming less of a requirement in our ever more connected world there are still plenty of places with less than stellar connectivity (cough Leeds Digital Garage cough). For such places it's extremely useful not only to have the command line docs detailed above (which are necessarily offline) but to have the nicely rendered HTML output too (with all its fancy images and extra chapters).
Again, this is relatively easy to do with the sphinx tooling for ReST. In picamera I have the python-picamera-docs package in Raspbian containing the complete docs available for offline viewing (install it and you'll find them under /usr/share/doc/python-picamera-docs/). This is produced from the same ReST source that generates the online docs for ReadTheDocs, which in turn automatically incorporates all the inline docstrings.
I'm not aware of MD tooling that allows this same facility, at least with similar ease to sphinx (it's especially notable that sphinx does most of the work for integrating the offline docs with Debian's doc-base system). Still, I may be less than well informed and I'd at least be happy if we could generate a traditional python-gpiozero-docs package from the MD source.
Searching / indexing
Again, trivial with the sphinx tooling; it's all done automatically and the searching even works with the offline copy of the docs (it's just some local javascript accessing a pre-built index). There do appear to be several possibilities here for MD but I'm not aware of any with similar offline capabilities. Perhaps there's something I'm not aware of?
Cross-referencing
A quick example from the picraft vector chapter. Note the link to "dict" and "set". In the source ReST these are as simple as:
...However, it conveys an extremely important capability in
Python: only immutable objects may be keys of a :class:`dict`
or members of a :class:`set`...
Sphinx looks for the "dict" and "set" classes within picraft, realizes they don't exist, then goes and looks in the indexes of the defined inter-sphinx docs. It finds them there and links to them.
Note at the moment the inter-sphinx link is defined as targetting Python 3.2. This is because I'm aware the foundation wishes to push Python 3 as the version of Python to learn, and because 3.2 is the current version of Python 3.x available on Raspbian. I'm hoping the new Jessie based version of Raspbian will ship with Python 3.4 (much better :) in which case all I need do to update any such links is change that inter-sphinx definition then rebuild the docs.
Again, this seems harder in MD?
Tables
Tables have a bit of a bad rep in ReST. This is largely because people aren't aware of the multiple different table types in ReST compared to MD's (well, GFM's anyway given that generic MD has no tables other than inline HTML). The classic ReST table (the one everyone complains about) is indeed complicated:
+------------------+---------------------+
| This is | a table in ReST |
+==================+=====================+
| It includes the | But these are only |
| ability to span | easy to construct |
| contents across | if you have a table |
| multiple rows or | capable editor like |
| columns. | emacs or vim |
+------------------+---------------------+
Personally (being a vimmie) I rather like these, because they fulfil goal 1 of the ReST project. However, I can well understand why people not accustomed to emacs or vim find them fiendishly difficult to construct. There's also the "simple table":
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
However, these are also (rightly) considered too complex due to the alignment requirement. The two table types no-one seems aware of (probably because they're buried in the directives docs away from the obvious "Tables" section) are the ludicrously simple CSV table:
.. csv-table::
This is,a table,that
I constructed,in Excel,then copied
and pasted,into my,ReST doc
And the slightly bizarre list table:
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
The observant will note from the docs that you could easily copy and paste a GFM table with csv-table by adding :delim: | as an option.
Personally I'm not so enamoured of csv-table simply because it violates goal 1 of ReST (the table isn't as readable "raw" which means it's not as readable to command line help readers). Still, at least it's present so authors have a means of constructing tables almost as simply as they can in GFM.
Conclusion
As mentioned above, I'm a fan of MD for simple documents. However, my opinion is that comprehensive documentation for a Python project goes beyond what MD can easily achieve (bearing in mind that the presumed reason for the selection of MD is its very simplicity).
A quick summary of the two systems:
- Inline markup: For basic things (paragraphs, unordered lists, inline emphasis, headings) there's very little difference, and hence no real usability difference, between MD and ReST.
- Block markup: Admonitions (hints, warnings) are simpler in ReST (at least all the extensions I've seen for doing admonitions in MD are similar to ReST but I don't think people are generally aware of them as I've not seen them used extensively in practice).
- Tables: As noted above, ReST tables can be made almost as simple as GFM.
- Links: External document links are admittedly more complex in ReST (e.g.
See the Python home page http://www.python.org_ for info.) but then internal (and intersphinx) links are considerably simpler. In my experience you'll use a lot more internal links that external links in package documentation.
- Code: Code blocks are almost as simple in ReST as they are in MD (indented but with a
:: leader on the line above), although they include considerably more options in ReST (external file inclusion, line highlighting, and manual syntax selection which occasionally comes in handy). GFM has rather nice unindented code blocks but firstly these aren't as clear in the raw as an indented block, and secondly I'm not aware of any editors other than Notepad than can't block indent so it's not a serious imposition.
- Images: Images are arguably similar in complexity between the two (although very different in syntax). That said, sphinx does have a nice feature permitting different versions of the same image to be used for different targets (e.g. PNG for HTML output, EPS for PDF output); a feature I use quite extensively by using SVG for the source format, and having a Makefile spit out the relevant formats at build time.
Finally, generation of different types of documentation (online, offline, command line) appears considerably simpler with ReST's sphinx tooling, but then I may not be aware of other options with MD here (please feel free to educate me!).
Anyway, my thanks to any reader that makes it through this mammoth screed. I await your consideration!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent