diff --git a/docs/using/on_rtd.md b/docs/using/on_rtd.md new file mode 100644 index 00000000..038d079f --- /dev/null +++ b/docs/using/on_rtd.md @@ -0,0 +1,48 @@ +# Using on ReadTheDocs + +This page describes how to get started with using the MyST parser for documentation generated by and hosted on [Read the Docs](https://readthedocs.org/), which "simplifies software documentation by automating building, versioning, and hosting of your docs for you". + +## Example minimal setup + +A `.readthedocs.yml` file with this content: + +```yaml +version: 2 +sphinx: + configuration: docs/conf.py +python: + version: 3 + install: + - requirements: docs/requirements.txt +``` + +```{tip} +See [Read The Docs' configuration file documentation](https://docs.readthedocs.io/en/stable/config-file/index.html) for more +``` + +A `docs/requirements.txt` with at least this content: + +```txt +myst-parser[sphinx] +``` + +A `docs/conf.py` file with at least this content: + +```python +extensions = [ + 'myst_parser', +] + +source_suffix = ['.rst', '.md'] +``` + +```{tip} +Use `sphinx-quickstart` to create your `conf.py` file and make the above modifications; see [Getting Started with Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#quick-start) for more. Just remember that to enable markdown-formatted documentation, you're using MyST Parser *instead* of ReCommonMark. (You still get all of CommonMark, and more!) +``` + +And now you're good to go, using MyST for your Sphinx-powered, ReadTheDocs-hosted documentation! + +```{seealso} +- [Read the Docs documentation](https://docs.readthedocs.io/en/stable/index.html) +- [The MyST Syntax Guide](example_syntax) +```