Docs: Adds Myst to the getting started with sphinx

[Pradhvan]

Myst is a more maintained and feature complete version of markdown for Sphinx.
Updated getting-started-with-sphinx.rst and added Myst instalation
guide under using-markdown-with-sphinx section.

Closes #7937

[stsewd]

Thanks! We should also link to the myst documentation.

[stsewd]

I think we can remove or update this warning, myst does support directives and roles.

[Pradhvan]

Let me remove the warning and update the PR.

[Pradhvan]

@stsewd on second thought, I think it's best to just update the warning. As the warning also mentioned to use reStructuredText instead of markdown with a blog post. So I think it would benefit anyone waiting to write documentation but is confused between markdown and reStructuredText

[stsewd]

We could move this link to the Using Markdown with Sphinx section so is easy to find. Something like You can use Markdown using MyST_

[Pradhvan]

Sure 👍🏾

[stsewd]

Thanks!

[jivanpal]

As a result of this PR, the docs now say:

You can use Markdown using MyST and reStructuredText in the same Sphinx project. We support this natively on Read the Docs, ...

However, trying to build a project that uses MyST on Read the Docs does not actually seem to work. Excerpts from my builds:

ModuleNotFoundError: No module named 'myst_parser'

sphinx.errors.ExtensionError: Could not import extension myst_parser (exception: No module named 'myst_parser')

Extension error:
Could not import extension myst_parser (exception: No module named 'myst_parser')

Read the Docs build numbers:

• 13172208
• 13172233
• 13172309
• 13172336
• 13172341

Also, the name of the package is myst-parser (with hyphen), but the name of the extension is myst_parser (with underscore), so the following needs to be corrected accordingly:

Then in your conf.py:

extensions = ['myst-parser']

My documentation generates perfectly locally.

[Pradhvan]

@jivanpal in the rst file does mention to use extensions = ['myst-parser'] in the conf.py

[jivanpal]

@Pradhvan I am using extensions = ['myst_parser'] as is actually required; see the MyST documentation. Attempting to use extensions = ['myst-parser'] instead and then build on Read the Docs causes a similar error (see mentioned build 13172336), and also causes generation to fail locally, because myst-parser is not the name of the extension.

[Pradhvan]

@jivanpal created a PR #7991 Thank you ❤️

[jivanpal]

However, trying to build a project that uses MyST on Read the Docs does not actually seem to work.

Turns out that I needed to specify myst-parser as a dependency. From the phrase "We support this natively on Read the Docs", I thought Read the Docs would already have the package installed, or otherwise detect the dependency, but this is clearly not the case. This necessity isn't mentioned in intro/getting-started-with-sphinx where MyST is mentioned, so if this were mentioned with a link to e.g. guides/reproducible-builds, I think this would avoid MyST users from having this problem in future.

My project is now building successfully on Read the Docs. 😁  For anyone who comes across this comment in the same situation, I achieved this by creating a /.readthedocs.yml and /docs/requirements.txt in my repo, specifying myst-parser in the latter.

# /.readthedocs.yml

version: 2

sphinx:
  configuration: docs/conf.py

python:
  version: 3.8
  install:
    - requirements: docs/requirements.txt

# /docs/requirements.txt

sphinx==3.5.1
sphinx_rtd_theme==0.5.1
myst-parser==0.13.5

[stsewd]

Turns out that I needed to specify myst-parser as a dependency. From the phrase "We support this natively on Read the Docs", I thought Read the Docs would already have the package installed

Yeah, we should make that more clear, maybe remove that wording and put an example of the config/requirements file

[Pradhvan]

@stsewd I can draft a different PR for this weekend. 😄

Yeah, we should make that more clear, maybe remove that wording and put an example of the config/requirements file