From a248602989c5fe555bc46dc59992ef0df625e7e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?benjamin=20melan=C3=A7on?= Date: Wed, 3 Jun 2020 08:42:09 -0400 Subject: [PATCH 1/3] Add using on Read The Docs instructions --- docs/using/on_rtd.md | 47 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/using/on_rtd.md diff --git a/docs/using/on_rtd.md b/docs/using/on_rtd.md new file mode 100644 index 00000000..89a20411 --- /dev/null +++ b/docs/using/on_rtd.md @@ -0,0 +1,47 @@ +# 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} + +``` From 22edde5282c2f197e5ece7747ffacade306d21f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?benjamin=20melan=C3=A7on?= Date: Wed, 3 Jun 2020 09:02:41 -0400 Subject: [PATCH 2/3] Fill out see also section --- docs/using/on_rtd.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/using/on_rtd.md b/docs/using/on_rtd.md index 89a20411..4377bfb7 100644 --- a/docs/using/on_rtd.md +++ b/docs/using/on_rtd.md @@ -43,5 +43,6 @@ Use `sphinx-quickstart` to create your `conf.py` file and make the above modific 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) +- {ref}`The MyST Syntax Guide ` ``` From 8383c76f214aec66570d9fe1d9d324868842afa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Melan=C3=A7on?= Date: Thu, 18 Jun 2020 14:22:20 -0400 Subject: [PATCH 3/3] Use MyST-enabled simpler syntax to link to syntax guide! Co-authored-by: Chris Sewell --- docs/using/on_rtd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/on_rtd.md b/docs/using/on_rtd.md index 4377bfb7..038d079f 100644 --- a/docs/using/on_rtd.md +++ b/docs/using/on_rtd.md @@ -44,5 +44,5 @@ And now you're good to go, using MyST for your Sphinx-powered, ReadTheDocs-hoste ```{seealso} - [Read the Docs documentation](https://docs.readthedocs.io/en/stable/index.html) -- {ref}`The MyST Syntax Guide ` +- [The MyST Syntax Guide](example_syntax) ```