Migrate documentation from reStructuredText to MyST Markdown

[evanroyrees]

1. Convert documentation to markdown format for ability to copy code blocks by simply clicking the copy button that appears in the code block rather than having to drag the cursor to copy.

I think there may be tools out there to perform this automagically?

• readthedocs on migrating from rst to md 👀

• rst2myst convert 👀

• Could also just continue on with current docs, but use md instead of rst by adding a markdown parser extension - sphinx markdown extension

• pandoc - gist for rst2md using pandoc

2. Add examples gallery - sphinx-gallery

[jason-c-kwan]

So would converting still allow integration with readthedocs.org?

[evanroyrees]

Yes, this is mentioned in readthedocs. They have put together a guide to do just this

[kaw97]

I don't think converting to markdown is the best way to do this. I successfully converted to markdown, but it broke autodoc, which is hard-coded for rst. This suggests a workaround, but I think I found a better solution: https://myst-parser.readthedocs.io/en/stable/faq/index.html#howto-autodoc

There is a sphinx extension called sphinx-copybutton.

I added it to my docker image and the .conf file and it appears to be working, which solved the problems I mentioned to Sidd last week. https://stackoverflow.com/questions/39187220/how-to-add-a-copy-button-in-the-code-blocks-for-rst-read-the-docs

Next, getting sphinx-gallery working and to make images/animations of it running.

[kaw97]

Completed with pull request #293