[PATCH 0/6] Documentation, reStructuredText and readthedocs.org

[Damien Lespiau]

On Wed, Sep 30, 2015 at 07:01:37PM +0100, Finucane, Stephen wrote:
> Could you kindly elaborate a little further on why you though it
> necessary to transition to reStructuredText? We're not making use of
> any of the fancy features of rest but it's still adds a lot of cruft
> (a Makefile? In a Python project? Surely not! :D).

I wish you wouldn't use any kind of dogma to judge work. Why would one
not use make and makefiles when it's handy to do so?

FWIW, this makefile is autogenerated by sphinx, the tool used to
document python itself and a multitude of python projects.

> There's also the fact that reST looks awful on GitHub

The 'fact'? I beg to differ:

  https://github.com/dlespiau/patchwork/blob/20150929-readthedocs/docs/installation.rst
  https://github.com/dlespiau/patchwork/blob/for-upstream/docs/installation.md

> and is a good deal more difficult to write than Markdown.

'good deal'?

  https://raw.githubusercontent.com/dlespiau/patchwork/20150929-readthedocs/docs/installation.rst
  https://raw.githubusercontent.com/dlespiau/patchwork/for-upstream/docs/installation.md

> As for integration with the Python ecosystem, while this is certainly
> true is some cases (OpenStack are currently undergoing a transition
> from XML-based DocBook, for example, but they're dealing with a
> *crazy* amount of documentation)

I don't see where you are going here.

> it's worth noting that tools like Markdown are very much a first class
> citizen on ReadTheDocs and in Python these days.

I did try and it was painful to make it work. Markdown is really for
small snippets of text and doesn't include anything for bigger
documentation projects.

Another thing is that the core of markdown is very small (too small):

  https://daringfireball.net/projects/markdown/syntax
  
Because of that, markdown renderers have to add more features to the
language, that's what github did:

  https://help.github.com/articles/github-flavored-markdown/

Of course, that means every markdown parser/renderer will have its own
idea of what markdown is.

All markdown renderers include a subset of HTML to offer a fallback when
markdown is not enough (usually just on the typography side, ie. not
document strucutre)

Other random thoughts, what about:
  - documentation composed of multiple files? that's not native
    markdown.
  - table of contents? How do you setup the number of levels to display in the ToC?
  - titles for images/figures?
  - There's no way to say what language a block of code is in native
    markdown (there are several extensions including that feature
    though)
  - cross references to other parts of the documentation?
  - ...

Overall, I don't think markdown offers enough documentation authoring
tools for project-wide documentation. There are other alternatives that
would work as well (asciidoc comes to mind), but given that it's a
python project, I went for sphinx and reStructuredText.

-- 
Damien