Instructions for using on RTD

[choldgraf]

A few folks now have run into gotchas or had confusion about how to use MyST on readthedocs. We should add short instructions for how to configure a repository to do so. I think probably this just means including instructions on how to install the right packages on RTD.

[chrisjsewell]

I think probably just make sphinx a core requirement, rather than an extra requirement will fix this. I originally wanted to keep sphinx an extra when this package contained aspects of the markdown parsing, which is not really the case any more, so I doubt there is really any use for it which doesn't include sphinx

[mlncn]

With nothing but myst_parser[sphinx] in requirements.txt i tried this morning and got this build error:

DEPRECATION: Python 2.7 reached the end of its life on January 1st, 2020. Please upgrade your Python as Python 2.7 is no longer maintained. pip 21.0 will drop support for Python 2.7 in January 2021. More details about Python 2 support in pip, can be found at https://pip.pypa.io/en/latest/development/release-process/#python-2-support
ERROR: Could not find a version that satisfies the requirement myst_parser[sphinx] (from -r requirements.txt (line 1)) (from versions: none)
ERROR: No matching distribution found for myst_parser[sphinx] (from -r requirements.txt (line 1))

And essentially the same error when i initially tried with a dash not an underscore, or without the [sphinx] part, whether myst-parser or myst_parser.

Should i try to include the git repository directly with git+https://github.com/executablebooks/MyST-Parser.git?

[chrisjsewell]

@mlncn it sounds like you have not created a readthedocs.yml for your repository, to configure how readthedocs build your documentation: https://docs.readthedocs.io/en/latest/config-file/v2.html, e.g.:

version: 2
python:
  version: 3
  install:
      - method: pip
        path: .

[mlncn]

@chrisjsewell ah! Thank you. Apologies, this project was set up in 2018 (cloned from an even earlier one) and i'm switching to MyST after your helpful note in ReCommonMark's queue. The conversion worked!

So i can vouch for the contents of my pull request, with the exception of the conf.py file— pretty sure at least an empty def setup(app): line will be needed at the bottom but i was trying to go minimal. Maybe the instructions just have to say to use sphinx-quickstart and modify. Will try to test later if no one else gets to it.

Thanks again!