From 0c826c3de31dfa91ce688e98b9d097245f8b43ac Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Fri, 13 Sep 2024 17:36:23 +0200 Subject: [PATCH] link to examples --- content/documentation.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/content/documentation.md b/content/documentation.md index 7185180..67c2f74 100644 --- a/content/documentation.md +++ b/content/documentation.md @@ -228,9 +228,11 @@ There are at least two ways to get started with Sphinx: 1. Try to open `_build/index.html` in your browser. -1. Experiment with adding more content, images, equations, code blocks. - - (we need examples here on how to do that) +1. Experiment with adding more content, images, equations, code blocks, ... + - [typography](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) + - [images](https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html) + - [math and equations](https://myst-parser.readthedocs.io/en/latest/syntax/math.html) + - [code blocks](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html) :::: There is a lot more you can do: @@ -243,17 +245,6 @@ There is a lot more you can do: every time you save a file - which makes writing and testing much easier. -## Confused about reStructuredText vs. Markdown vs. MyST? - -- At the beginning there was reStructuredText and Sphinx was built for reStructuredText. -- Independently, Markdown was invented and evolved into a couple of flavors. -- Markdown became more and more popular but was limited compared to reStructuredText. -- Later, [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) - was invented to be able to write - something that looks like Markdown but in addition can do everything that - reStructuredText can do with extra directives. - - ## Demo: Building documentation with GitHub Actions First we need to extend the `environment.yml` file to include the necessary packages: @@ -371,6 +362,17 @@ Then rebuild the documentation (or push the changes and let GitHub rebuild it) and you should see a new section "API Reference". +## Confused about reStructuredText vs. Markdown vs. MyST? + +- At the beginning there was reStructuredText and Sphinx was built for reStructuredText. +- Independently, Markdown was invented and evolved into a couple of flavors. +- Markdown became more and more popular but was limited compared to reStructuredText. +- Later, [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) + was invented to be able to write + something that looks like Markdown but in addition can do everything that + reStructuredText can do with extra directives. + + ## Where to read more - [CodeRefinery documentation lesson](https://coderefinery.github.io/documentation/) @@ -378,5 +380,4 @@ and you should see a new section "API Reference". - [Sphinx + ReadTheDocs guide](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html) - For more Markdown functionality, see the [Markdown guide](https://www.markdownguide.org/basic-syntax/). - For Sphinx additions, see [Sphinx Markup Constructs](https://www.sphinx-doc.org/en/master/markup/index.html). -- [https://docs.python-guide.org/writing/documentation/](https://docs.python-guide.org/writing/documentation/) -- [MyST parser](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) +- [An opinionated guide on documentation in Python](https://docs.python-guide.org/writing/documentation/)