Consider translating documentation to markdown

[bgoli]

Consider changing the documentation format https://pyscesdocs.readthedocs.org to Markdown. We would then probably also need a Markdown --> ReST converter for Sphinx.

[jmrohwer]

Not sure why you would want this? The documentation is all there and written. Sphinx needs ReST AFAICT. RTD runs Sphinx on the ReST source it automatically pulls in from GitHub.

Pandoc is quite good at interconverting all these formats, but for the docs I'd prefer to have them in ReST since that is what Sphinx uses, and we would have to have to check in any case if the conversion MD->ReST went without error. So the "authoritative version" should be ReST as that is what Sphinx uses.

If a new set section/chapter docs has to be written and you prefer writing MD, I'd rather suggest writing the first version in MD and then using pandoc to convert it to ReST.

[bgoli]

I've had good experiences with Pandoc and markdown to other things . The advantage is that all documentation could then be be in Markdown and we can do fancy things with Pandoc (like includes).