Render .md files on RTD with MyST-parser

[mwouts]

With this PR we switch from using recommonmark to myst-parser for parsing .md files on RTD, as suggested by @willingc at #347.

I must say that this is my first experience with using myst-parser on RTD, so it is probably a good idea to read the warnings carefully. When I run make html I see a series of new warnings WARNING: Non-consecutive header level increase; 0 to 2.

Other than that, at first sight I see no difference on the html files.

The full output is

sphinx-build -b html -d build/doctrees  -n source build/html
Running Sphinx v3.2.1
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
myst v0.12.10: MdParserConfig(renderer='sphinx', commonmark_only=False, dmath_enable=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, amsmath_enable=False, deflist_enable=False, update_mathjax=True, admonition_enable=False, figure_enable=False, disable_syntax=[], html_img_enable=False, url_schemes=None, heading_anchors=None)
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] websocket-mode                                                                            
/home/marc/GitHub/kernel_gateway/docs/source/config-options.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/devinstall.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/features.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/getting-started.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/http-mode.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/troubleshooting.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/uses.md:1: WARNING: Non-consecutive header level increase; 0 to 2
/home/marc/GitHub/kernel_gateway/docs/source/websocket-mode.md:1: WARNING: Non-consecutive header level increase; 0 to 2
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] websocket-mode                                                                             
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: 'myst' reference target not found: _modules/kernel_gateway/jupyter_websocket.html
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: 'myst' reference target not found: _modules/kernel_gateway/notebook_http.html
generating indices...  genindexdone
writing additional pages...  searchdone
copying images... [100%] images/tmpnb_kernel_gateway.png                                                            
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 11 warnings.

The HTML pages are in build/html.

Build finished. The HTML pages are in build/html.

[willingc]

@mwouts Pretty sure that those warnings happen when the source doc doesn't have h1, h2, etc. (#, ##, etc.) in the markdown.

[kevin-bates]

Looks like myst_parser requires headers to be consecutive and starting at h1. In all of the "header" warnings above, the top-most header starts at h2. Decreasing the header levels by 1 on each of those pages will remove those warnings (including those pages where there are subsequent levels present).

These warnings:

/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: 'myst' reference target not found: _modules/kernel_gateway/jupyter_websocket.html
/home/marc/GitHub/kernel_gateway/docs/source/plug-in.md:39: WARNING: 'myst' reference target not found: _modules/kernel_gateway/notebook_http.html

Can be fixed by this update:

  [kernel_gateway.jupyter_websocket](websocket-mode.md) and  [kernel_gateway.notebook_http](http-mode.md).

[mwouts]

Thank you Carol, Kevin for the hints. I'll update the PR accordingly in the evening.

[mwouts]

With the commits above there is no warning any more when I do make html (and the HTML documentation generated locally seems perfectly right).

[kevin-bates]

LGTM - thank you Marc.