Choosing documentation syntax; rst vs. md?

[ahojukka5]

We have already discussed this in context of docstrings but I think this needs another verification because this affects to all documentation we making in future. Some of our documents are now rst and some are md. I think we need to choose one and keep on that.

Already known is that

• rst is default for sphinx while md is default for mkdocs
• IPython nbconvert renders good rst and not-so-good md
• Lexicon writes md using Markdown.jl
• rst has more features than md, like toctree (=structure)
• rst is feature richer in all measures, md doesn't have actual "structure"?
• rst documents are nicely rendered to pdf
• md documents are easier for human eye
• numpydoc is some kind of variant from rst
• almost all(?) python documentation is documented using rst
• julia itself uses rst for documentation
• github supports both rst and md (and they have their own "github variation" from original md)

Some links related to this

• http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext
• http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html ("Please note that, anywhere I say “Markdown” below, if there’s any ambiguity, I specifically mean “Pandoc Markdown”. Gruber’s original Markdown lacks a number of the modern niceties which Pandoc-Markdown provides.") (this has been already discussed in Coding style #5).

Do you have any opinions for this? I personally suggest that we use rst in our documentation, mainly because I don't see any good (enough) reasons to use md.

Consequences:

md -> rst : change filename extensions, fix links, find a way to generate api documentation
rst -> md: change filename extensions, change sphinx -> mkdocs in dgs, fix links, find a way to render notebooks

[TeroFrondelius]

Same same but different. I vote rst and numpy documentation style.

[ovainola]

md -> rst : I think we already at a point where almost everything is rst except the api documentation. I already tried the rst parser solution provided by @MichaelHatherly in #4 but this seems to provide the rendering in REPL (symbol ?). I guess we are looking for the save function which generates the documentation files. Options could be that we'd write the functionality in julia (REPL renderer & save function, this would help the community also) or, since we already discussed about sphinx, write a functionality for sphinx to process julia files (already has rst renderer, has to find the docstring from the source files).

rst -> md : We're already using Lexicon to create api documention (no worries there) but the notebooks are a bit problematic. Ipython nbconvert has a functionality to generate .md but when me and @ahojukka5 tested it, mkdocs it didn't render them quite well (all code parts we more like one long inline function). Is there any other way/program to convert notebooks? Maybe if we convert notebooks straight to html although this causes a bit friction on the server side when we have to manually move files to correct directories. Sounds more like spaghetti than solution 😆.

I vote for rst even if it's a bit more work.

[ahojukka5]

Ok, I just wanted to double check this. I updated CONTRIBUTING.md.