diff --git a/content/building.md b/content/building.md new file mode 100644 index 0000000..5a4911c --- /dev/null +++ b/content/building.md @@ -0,0 +1,14 @@ +# Building the lesson + +It is built the normal Sphinx way: + +``` +make html +# or +make dirhtml +# full build +make clean html +``` + +However, there are different ways to set up a Sphinx project. Our +sample project puts the results in `_build/`. diff --git a/content/building.rst b/content/building.rst deleted file mode 100644 index 4621039..0000000 --- a/content/building.rst +++ /dev/null @@ -1,13 +0,0 @@ -Building the lesson -=================== - -It is built the normal Sphinx way:: - - make html - # or - make dirhtml - # full build - make clean html - -However, there are different ways to set up a Sphinx project. Our -sample project puts the results in ``_build/``. diff --git a/content/changelog.md b/content/changelog.md new file mode 100644 index 0000000..954fe96 --- /dev/null +++ b/content/changelog.md @@ -0,0 +1,5 @@ +# Changelog + +## 0.8.0 + +- First PyPI release diff --git a/content/changelog.rst b/content/changelog.rst deleted file mode 100644 index f6456f5..0000000 --- a/content/changelog.rst +++ /dev/null @@ -1,7 +0,0 @@ -Changelog -========= - -0.8.0 ------ - -* First PyPI release diff --git a/content/cheatsheet.rst b/content/cheatsheet.md similarity index 53% rename from content/cheatsheet.rst rename to content/cheatsheet.md index 60b605f..90c5b84 100644 --- a/content/cheatsheet.rst +++ b/content/cheatsheet.md @@ -1,4 +1,3 @@ -Cheatsheet -========== +# Cheatsheet This is the cheatsheet. diff --git a/content/conf.py b/content/conf.py index 6c265b4..9359ce0 100644 --- a/content/conf.py +++ b/content/conf.py @@ -54,6 +54,11 @@ #nb_execution_mode = "force" nb_execution_mode = "cache" +# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html +myst_enable_extensions = [ + "colon_fence", +] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/content/contributing-to-a-lesson.md b/content/contributing-to-a-lesson.md new file mode 100644 index 0000000..354d341 --- /dev/null +++ b/content/contributing-to-a-lesson.md @@ -0,0 +1,129 @@ +# Quickstart: Contributing to a lesson + +If you are at this page, you might want to quickly contribute to some +existing material using the `sphinx-lesson` format. Luckily, this +is fairly easy: + +- Get the source +- Edit the material in the `content/` directory +- (optional) Set up the Python environment and preview +- Send your contribution + +In summary, each lesson is a Python project, with content in the +`content/` directory. It uses the Sphinx documentation system, +which is a popular, extendable tool. We have only minor extensions to +make it suitable to lessons. + +Instead of going through this process, you can also open an issue +instead with your proposed change, and let someone else add it. + +```{highlight} console +``` + +## Get the lesson material + +You need to consult with the lesson you would like to edit. If this +is using the `git` version control system on Github, you could clone +it like this: + +``` +$ git clone git://github.com/ORGANIZATION/LESSON.git +``` + +[CodeRefinery's git-intro lesson](https://coderefinery.github.io/git-intro/) explains more. + +## Edit the material + +The material is in the `content/` directory. Depending on the +lesson, in may be in ReStructured Text, MyST Markdown, or Jupyter +notebooks. + +### ReStructured Text and MyST Markdown + +You will probably copy existing examples, but you can also see +{doc}`our quick guide `. The main thing to note is that +this is not unstructured Markdown, but there are particular +(non-display) **directives** and **roles** to tag blocks and inline +text. (In fact, "markdown" is a broad concept and everyone uses some +different extensions of it). + +- {doc}`md-and-rst` +- {ref}`ReStructured Text reference ` +- [MyST reference](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) +- {doc}`sphinx-lesson directives for markup ` + +*Do not worry about getting syntax right*. Send your improvement, and +editing is easy and you will learn something. + +### Jupyter notebooks + +Jupyter notebooks are a common format for computational narratives, +and can be natively used with Sphinx via [myst-nb](https://myst-nb.readthedocs.io/). Note that you should use MyST +Markdown directives and roles (see previous section) in the notebook +to give structure to the material. + +Again, *do not worry about getting the syntax right*. This is the +least important part of things. + +## Build and test locally + +Generic: The `requirements.txt` file includes all Python dependencies +to build the lesson. The lesson can be built with `sphinx-build -M +html content/ _build`, or `make html` if you have Make installed. + +Or in more detail: + +Create a virtual environment to install the requirements (a conda +environment would work just as well): + +``` +$ python3 -m venv venv/ +$ source venv/bin/activate +``` + +:::{note} +if `python3 -m venv venv/` does not work, try with `python -m venv venv/` +::: + +Then upgrade pip inside the virtual environment and install dependencies (it is recommended that conda base environment is deactivated): + +``` +$ pip install --upgrade pip +$ pip install -r requirements.txt +``` + +You can build it using either of these commands: + +``` +$ sphinx-build -M html content/ _build +$ make html # if you have make installed +``` + +And then view it with your web browser. Remove the `_build` +directory to force a clean rebuild (or `make clean`). + +Or you can use the **Sphinx autobuilder**, which will start a process +that rebuilds it on every change, and starts a web server to view it. +It will tell you how to access the server: + +``` +$ sphinx-autobuild content/ _build/ +... +[I ...] Serving on http://127.0.0.1:8000 +``` + +## Sending your changes back + +This depends on the project, but can be done using Github pull +requests. [CodeRefinery's git-collaborative lesson](https://coderefinery.github.io/git-collaborative/) goes into +details about pull requests. + +## Other things to keep in mind + +- Make sure that you have rights to submit your change. In general, + if you reuse anything else that already exists, explain this in your + pull request. +- *Content and ideas are more important than markup*. Don't worry + about doing something wrong, that is why we have review! +- Many different people use the lessons. Ask before doing things that + make the lesson too specific to your use case. diff --git a/content/contributing-to-a-lesson.rst b/content/contributing-to-a-lesson.rst deleted file mode 100644 index c1a55dd..0000000 --- a/content/contributing-to-a-lesson.rst +++ /dev/null @@ -1,135 +0,0 @@ -Quickstart: Contributing to a lesson -==================================== - -If you are at this page, you might want to quickly contribute to some -existing material using the ``sphinx-lesson`` format. Luckily, this -is fairly easy: - -* Get the source -* Edit the material in the ``content/`` directory -* (optional) Set up the Python environment and preview -* Send your contribution - -In summary, each lesson is a Python project, with content in the -``content/`` directory. It uses the Sphinx documentation system, -which is a popular, extendable tool. We have only minor extensions to -make it suitable to lessons. - -Instead of going through this process, you can also open an issue -instead with your proposed change, and let someone else add it. - -.. highlight:: console - - - -Get the lesson material ------------------------ - -You need to consult with the lesson you would like to edit. If this -is using the ``git`` version control system on Github, you could clone -it like this:: - - $ git clone git://github.com/ORGANIZATION/LESSON.git - -`CodeRefinery's git-intro lesson -`__ explains more. - -Edit the material ------------------ - -The material is in the ``content/`` directory. Depending on the -lesson, in may be in ReStructured Text, MyST Markdown, or Jupyter -notebooks. - -ReStructured Text and MyST Markdown -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You will probably copy existing examples, but you can also see -:doc:`our quick guide `. The main thing to note is that -this is not unstructured Markdown, but there are particular -(non-display) **directives** and **roles** to tag blocks and inline -text. (In fact, "markdown" is a broad concept and everyone uses some -different extensions of it). - -* :doc:`md-and-rst` -* :ref:`ReStructured Text reference ` -* `MyST reference `__ -* :doc:`sphinx-lesson directives for markup ` - -*Do not worry about getting syntax right*. Send your improvement, and -editing is easy and you will learn something. - -Jupyter notebooks -~~~~~~~~~~~~~~~~~ - -Jupyter notebooks are a common format for computational narratives, -and can be natively used with Sphinx via `myst-nb -`__. Note that you should use MyST -Markdown directives and roles (see previous section) in the notebook -to give structure to the material. - -Again, *do not worry about getting the syntax right*. This is the -least important part of things. - - - -Build and test locally ----------------------- - -Generic: The ``requirements.txt`` file includes all Python dependencies -to build the lesson. The lesson can be built with ``sphinx-build -M -html content/ _build``, or ``make html`` if you have Make installed. - -Or in more detail: - -Create a virtual environment to install the requirements (a conda -environment would work just as well):: - - $ python3 -m venv venv/ - $ source venv/bin/activate - -.. note:: - - if ``python3 -m venv venv/`` does not work, try with ``python -m venv venv/`` - -Then upgrade pip inside the virtual environment and install dependencies (it is recommended that conda base environment is deactivated):: - - $ pip install --upgrade pip - $ pip install -r requirements.txt - -You can build it using either of these commands:: - - $ sphinx-build -M html content/ _build - $ make html # if you have make installed - -And then view it with your web browser. Remove the ``_build`` -directory to force a clean rebuild (or ``make clean``). - -Or you can use the **Sphinx autobuilder**, which will start a process -that rebuilds it on every change, and starts a web server to view it. -It will tell you how to access the server:: - - $ sphinx-autobuild content/ _build/ - ... - [I ...] Serving on http://127.0.0.1:8000 - - -Sending your changes back -------------------------- - -This depends on the project, but can be done using Github pull -requests. `CodeRefinery's git-collaborative lesson -`__ goes into -details about pull requests. - - -Other things to keep in mind ----------------------------- - -* Make sure that you have rights to submit your change. In general, - if you reuse anything else that already exists, explain this in your - pull request. -* *Content and ideas are more important than markup*. Don't worry - about doing something wrong, that is why we have review! -* Many different people use the lessons. Ask before doing things that - make the lesson too specific to your use case. diff --git a/content/convert-old-lessons.md b/content/convert-old-lessons.md new file mode 100644 index 0000000..27748a8 --- /dev/null +++ b/content/convert-old-lessons.md @@ -0,0 +1,95 @@ +# Converting an old lesson + +% highlight: console + +## Convert a Jekyll lesson + +This brings in the necessary files + +Add the template lesson as a new remote: + +``` +git remote add s-l-t https://github.com/coderefinery/sphinx-lesson-template.git +git fetch s-l-t +``` + +Check out some basic files into your working directory. Warning: if +you add a `.github/workflows/sphinx.yml` file, even a push to a +branch will **override github pages**: + +``` +git checkout s-l-t/main -- requirements.txt +git checkout s-l-t/main -- .github/workflows/sphinx.yml +``` + +If you need more Sphinx files: + +``` +git checkout s-l-t/main -- content/conf.py +git checkout s-l-t/main -- .gitignore Makefile make.bat +``` + +If you need the full content (only `index.rst` for now): + +``` +git checkout s-l-t/main -- content/ +``` + +(if jekyll conversion) Move content over: + +``` +git mv _episodes/* content/ +``` + +(if jekyll conversion) Copy stuff from `index.md` into `content/index.rst`. + +(if jekyll conversion) Remove old jekyll stuff: + +``` +git rm jekyll-common/ index.md _config.yml Gemfile .gitmodules +``` + +Set up github pages (first commit to trigger CI), see {doc}`installation`: + +``` +git checkout -b gh-pages origin/gh-pages +git commit -m 'empty commit to trigger gh-pages' --allow-empty +git push +``` + +Do all the rest of the fixing... all the bad, non-portable, +non-relative markdown and so on. This is the hard part. Common +problems: + +- Non-consecutive section headings +- Multiple top-level section headings (there should be one top-level + section heading that is the page title) +- Weird relative links (most work though) + +You can also update your local view of the default branch: + +``` +git remote set-head origin --auto +``` + +## Joint history + +This option joins the histories of the two repositories, so that you +could merge from the template repository to keep your files up to +date. **This may not currently work**, and also may not have any +value (but is kept here for reference until later). + +Merge the two unrelated histories: + +``` +$ git remote add template https://github.com/coderefinery/sphinx-lesson-template +$ git fetch template +$ git merge template/main --allow-unrelated-histories +# Resolve any possible merge conflicts +$ git checkout --theirs .gitignore +$ git checkout --ours LICENSE +$ git add .gitignore LICENSE +$ git commit -m 'merge sphinx-lesson history to this lesson' +``` + +Then proceed like the previous section shows. diff --git a/content/convert-old-lessons.rst b/content/convert-old-lessons.rst deleted file mode 100644 index 6911bd5..0000000 --- a/content/convert-old-lessons.rst +++ /dev/null @@ -1,84 +0,0 @@ -Converting an old lesson -======================== - -.. highlight: console - - -Convert a Jekyll lesson ------------------------ - -This brings in the necessary files - -Add the template lesson as a new remote:: - - git remote add s-l-t https://github.com/coderefinery/sphinx-lesson-template.git - git fetch s-l-t - -Check out some basic files into your working directory. Warning: if -you add a ``.github/workflows/sphinx.yml`` file, even a push to a -branch will **override github pages**:: - - git checkout s-l-t/main -- requirements.txt - git checkout s-l-t/main -- .github/workflows/sphinx.yml - -If you need more Sphinx files:: - - git checkout s-l-t/main -- content/conf.py - git checkout s-l-t/main -- .gitignore Makefile make.bat - -If you need the full content (only ``index.rst`` for now):: - - git checkout s-l-t/main -- content/ - -(if jekyll conversion) Move content over:: - - git mv _episodes/* content/ - -(if jekyll conversion) Copy stuff from ``index.md`` into ``content/index.rst``. - -(if jekyll conversion) Remove old jekyll stuff:: - - git rm jekyll-common/ index.md _config.yml Gemfile .gitmodules - -Set up github pages (first commit to trigger CI), see :doc:`installation`:: - - git checkout -b gh-pages origin/gh-pages - git commit -m 'empty commit to trigger gh-pages' --allow-empty - git push - -Do all the rest of the fixing... all the bad, non-portable, -non-relative markdown and so on. This is the hard part. Common -problems: - -* Non-consecutive section headings -* Multiple top-level section headings (there should be one top-level - section heading that is the page title) -* Weird relative links (most work though) - - -You can also update your local view of the default branch:: - - git remote set-head origin --auto - - - -Joint history -------------- - -This option joins the histories of the two repositories, so that you -could merge from the template repository to keep your files up to -date. **This may not currently work**, and also may not have any -value (but is kept here for reference until later). - -Merge the two unrelated histories:: - - $ git remote add template https://github.com/coderefinery/sphinx-lesson-template - $ git fetch template - $ git merge template/main --allow-unrelated-histories - # Resolve any possible merge conflicts - $ git checkout --theirs .gitignore - $ git checkout --ours LICENSE - $ git add .gitignore LICENSE - $ git commit -m 'merge sphinx-lesson history to this lesson' - -Then proceed like the previous section shows. diff --git a/content/directives.md b/content/directives.md new file mode 100644 index 0000000..24217a1 --- /dev/null +++ b/content/directives.md @@ -0,0 +1,238 @@ +# Directives + +:::{seealso} +In [Sphinx/Docutils, directives have a different meaning](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html). +Directives in sphinx-lesson are actually the special case of the +generic directive class called **admonitions**. +::: + +**Directives** are used to set off a certain block of text. They can +be used as an aside or block (e.g. `exercise`, `instructor-note`). +If the content of the box would be long (e.g. an entire episode is a +`type-along`, or an entire section is an `exercise`), you could use +the `type-along` directive to introduce the start of it but not put +all content in that directive. + +Sphinx and docutils calls these type of directives **admonitions** +(and "directive" is a more general concept) + +## How to use + +Example of `exercise`: + +:::{exercise} +Some body text +::: + +:::{exercise} Custom title +Some body text +::: + +:::{exercise} +::: + +````{list-table} +* * Markdown + + ```` + ```{exercise} + + Some body text + ``` + ```` + + ```` + ```{exercise} Custom title + + Some body text + ``` + ```` + + ```` + ```{exercise} + ``` + ```` + + + * ReST: + + ```` + .. exercise:: + + Some body text + ```` + + ```` + .. exercise:: Custom title + + Some body text + ```` + + ```` + .. exercise:: + ```` +```` + +You notice these directives can have optional a custom title. This is +an addition from regular Sphinx admonitions, and is *not* usable in +regular Sphinx admonition directives. Also, unlike regular Sphinx +admonitions, the content in our directives is optional, if you want to +use it as a simple section header. + +The `solution` directive begins collapsed (via [sphinx-togglebutton](https://github.com/executablebooks/sphinx-togglebutton)): + +:::{solution} +This is a solution +::: + +Directives are implemented in the Python package +`sphinx_lesson.directives` and can be used independently of the rest +of `sphinx-lesson`. + +## List + +Many directives are available. + +The following directives are used for exercises/solutions/homework. +They all render as green ("important" class: + +- `demo` +- `exercise` +- `solution` (toggleable, default hidden) +- `type-along` (most of the lessons are hands-on, so this is a bit + redundant. Use this when emphasizing a certain section is "follow + along", as opposed to watching or working alone.) +- `homework` + +Other miscellaneous directives: + +- `discussion` +- `instructor-note` +- `prerequisites` + +The following are Sphinx default directives that may be especially +useful to lessons. These do *not* accept an optional Title argument, +the title is hard-coded. + +- `see-also` +- `note` +- `important` (green) +- `warning` (yellow) +- `danger` (red + +The following are available, for compatibility with Carpentries styles: + +- `callout` +- `challenge` (alias to `exercise`) +- `checklist` +- `keypoints` (bottom of lesson) +- `objectives` (top of lesson) +- `prereq` (use `prerequisites` instead) +- `solution` (begins collapsed) +- `testimonial` +- `output` (use code blocks instead) +- `questions` (top of lesson) + +## Gallery + +This is a demonstration of all major directives + +### sphinx-lesson + +:::{demo} +demo +::: + +:::{demo} +::: + +:::{type-along} +type-along +::: + +:::{type-along} +::: + +:::{exercise} +exercise +::: + +:::{solution} +solution +::: + +:::{homework} +homework +::: + +:::{discussion} +discussion +::: + +:::{instructor-note} +instructor-note +::: + +:::{prerequisites} +prerequisites +::: + +### Sphinx default + +:::{note} +note +::: + +:::{important} +important +::: + +:::{seealso} +seealso +::: + +:::{warning} +warning +::: + +:::{danger} +danger +::: + +### Carpentries holdovers + +:::{questions} +questions +::: + +:::{objectives} +objectives +::: + +:::{keypoints} +keypoints +::: + +:::{callout} +callout +::: + +:::{challenge} +challenge +::: + +:::{checklist} +checklist +::: + +:::{prereq} +prereq +::: + +:::{testimonial} +testimonial +::: + +:::{output} +output +::: diff --git a/content/directives.rst b/content/directives.rst deleted file mode 100644 index 5a5bf06..0000000 --- a/content/directives.rst +++ /dev/null @@ -1,250 +0,0 @@ -Directives -========== - -.. seealso:: - - In `Sphinx/Docutils, directives have a different meaning - `__. - Directives in sphinx-lesson are actually the special case of the - generic directive class called **admonitions**. - -**Directives** are used to set off a certain block of text. They can -be used as an aside or block (e.g. ``exercise``, ``instructor-note``). -If the content of the box would be long (e.g. an entire episode is a -``type-along``, or an entire section is an ``exercise``), you could use -the ``type-along`` directive to introduce the start of it but not put -all content in that directive. - -Sphinx and docutils calls these type of directives **admonitions** -(and "directive" is a more general concept) - - - -How to use ----------- - -Example of ``exercise``: - -.. exercise:: - - Some body text - -.. exercise:: Custom title - - Some body text - -.. exercise:: - -.. list-table:: - - * * Markdown:: - - ```{exercise} - - Some body text - ``` - - :: - - ```{exercise} Custom title - - Some body text - ``` - - :: - - ```{exercise} - ``` - - - - * ReST:: - - .. exercise:: - - Some body text - - :: - - .. exercise:: Custom title - - Some body text - - :: - - .. exercise:: - - -You notice these directives can have optional a custom title. This is -an addition from regular Sphinx admonitions, and is *not* usable in -regular Sphinx admonition directives. Also, unlike regular Sphinx -admonitions, the content in our directives is optional, if you want to -use it as a simple section header. - - -The ``solution`` directive begins collapsed (via `sphinx-togglebutton -`__): - -.. solution:: - - This is a solution - -Directives are implemented in the Python package -``sphinx_lesson.directives`` and can be used independently of the rest -of ``sphinx-lesson``. - - - -List ----- - -Many directives are available. - -The following directives are used for exercises/solutions/homework. -They all render as green ("important" class: - -* ``demo`` -* ``exercise`` -* ``solution`` (toggleable, default hidden) -* ``type-along`` (most of the lessons are hands-on, so this is a bit - redundant. Use this when emphasizing a certain section is "follow - along", as opposed to watching or working alone.) -* ``homework`` - -Other miscellaneous directives: - -* ``discussion`` -* ``instructor-note`` -* ``prerequisites`` - -The following are Sphinx default directives that may be especially -useful to lessons. These do *not* accept an optional Title argument, -the title is hard-coded. - -* ``see-also`` -* ``note`` -* ``important`` (green) -* ``warning`` (yellow) -* ``danger`` (red - - -The following are available, for compatibility with Carpentries styles: - -* ``callout`` -* ``challenge`` (alias to ``exercise``) -* ``checklist`` -* ``keypoints`` (bottom of lesson) -* ``objectives`` (top of lesson) -* ``prereq`` (use ``prerequisites`` instead) -* ``solution`` (begins collapsed) -* ``testimonial`` -* ``output`` (use code blocks instead) -* ``questions`` (top of lesson) - - - -Gallery -------- - -This is a demonstration of all major directives - -sphinx-lesson -~~~~~~~~~~~~~ - -.. demo:: - - demo - -.. demo:: - -.. type-along:: - - type-along - -.. type-along:: - -.. exercise:: - - exercise - -.. solution:: - - solution - -.. homework:: - - homework - -.. discussion:: - - discussion - -.. instructor-note:: - - instructor-note - -.. prerequisites:: - - prerequisites - -Sphinx default -~~~~~~~~~~~~~~ - -.. note:: - - note - -.. important:: - - important - -.. seealso:: - - seealso - -.. warning:: - - warning - -.. danger:: - - danger - -Carpentries holdovers -~~~~~~~~~~~~~~~~~~~~~ - -.. questions:: - - questions - -.. objectives:: - - objectives - -.. keypoints:: - - keypoints - -.. callout:: - - callout - -.. challenge:: - - challenge - -.. checklist:: - - checklist - -.. prereq:: - - prereq - -.. testimonial:: - - testimonial - -.. output:: - - output diff --git a/content/exercise-list.rst b/content/exercise-list.md similarity index 57% rename from content/exercise-list.rst rename to content/exercise-list.md index 6cc1d86..493cffc 100644 --- a/content/exercise-list.rst +++ b/content/exercise-list.md @@ -1,47 +1,47 @@ -Exercise list -============= +# Exercise list -The ``exercise-list`` directive inserts a list of all exercise and -solution :doc:`directives ` (and maybe more). This can be +The `exercise-list` directive inserts a list of all exercise and +solution {doc}`directives ` (and maybe more). This can be useful as an overall summary of the entire lesson flow, onboarding new instructors and helpers, and more. -Usage ------ +## Usage -ReST:: +ReST: - .. exerciselist:: +``` +.. exerciselist:: +``` -MyST:: +MyST: - ```{exerciselist}``` +```` +```{exerciselist}``` +```` One can give the optional directive arguments to specify lists of -admonition classes to include (default: ``exercise``, ``solution``, -``exerciselist-include``) or exclude (default: -``exerciselist-exclude``) if you want to (any :doc:`directives -` which match any ``include``, and do not match any -``exclude`` are included). Specify the options this way (ReST):: +admonition classes to include (default: `exercise`, `solution`, +`exerciselist-include`) or exclude (default: +`exerciselist-exclude`) if you want to (any {doc}`directives +` which match any `include`, and do not match any +`exclude` are included). Specify the options this way (ReST): - .. exerciselist:: - :include: exercise solution instructor-note - :exclude: exclude-this +``` +.. exerciselist:: + :include: exercise solution instructor-note + :exclude: exclude-this - .. exercise:: - :class: exclude-this +.. exercise:: + :class: exclude-this +``` This feature is new as of early 2022, there may be possible problems in it still - please report. Currently, only sphinx-lesson admonitions can be included due to technical considerations (see source for hint on fixing). - - -.. _exerciselist_recommendations: - -Recommendations to make a useful list -------------------------------------- +(exerciselist-recommendations)= +## Recommendations to make a useful list - Context is important! Give your exercises a name other than the default of "Exercise", so that someone quickly scanning the exercise @@ -49,61 +49,64 @@ Recommendations to make a useful list - Making good summaries is really an important skill for organizing anything - give this the attention it needs. - - Think of an exercise leader or helper coming to help someone, seeing the exercise, and needing to help someone: not just what to do, but what the core lesson and task is, so that they can focus on giving the right help (and telling the learners what they don't need to worry about). - - Context can be both in the exercise title and in the exercise body itself. - Name the exercises well. Best is to think of it like a version control commit: an imperative sentence stating what the person will - do in the exercise. For example:: + do in the exercise. For example: - Make your first git commit - Resolve the conflict + ``` + Make your first git commit + Resolve the conflict + ``` -- In the title, include any other important information (see below):: +- In the title, include any other important information (see below): - Create a setup.py file for your package (15 min) - (optional) Install your package in editable mode using ``pip install -e`` (5 min) - (advanced) Also create packaging using pyproject.toml and compare (20 min) + ``` + Create a setup.py file for your package (15 min) + (optional) Install your package in editable mode using ``pip install -e`` (5 min) + (advanced) Also create packaging using pyproject.toml and compare (20 min) + ``` - Consider giving your exercises permanent identifiers. They are not auto-numbered yet for a reason (what happens when more exercises are added/removed?), but if you give them an ID, they will be findable - even later. Suggestion is ``Episodetopic-N``:: + even later. Suggestion is `Episodetopic-N`: - Basic-1: Verify git is installed - Basic-2: Initialize the repository - Conflicts-2: Create a new branch for the other commit. - Internals-1: (advanced): Inspect individual objects with ``git cat-file`` + ``` + Basic-1: Verify git is installed + Basic-2: Initialize the repository + Conflicts-2: Create a new branch for the other commit. + Internals-1: (advanced): Inspect individual objects with ``git cat-file`` + ``` - It could include not just what you do, but a bit about why you are doing it and what you are learning. -- The list includes only ``exercise``, ``type-along``, and ``solution``. For - backwards compatibility, ``challenge`` is also included. +- The list includes only `exercise`, `type-along`, and `solution`. For + backwards compatibility, `challenge` is also included. - Optional or advanced exercises should clearly state it in the exercise title, since people will browse the list separate from the main lesson material. -- Try to minimize use of ``:include:`` and ``:exclude:`` and use the +- Try to minimize use of `:include:` and `:exclude:` and use the defaults and adjust your directives to match sphinx-lesson semantics. Excess use of this may over-optimize for particular workshops - -Example -------- +## Example This section contains the exercise list of sphinx-lesson. Note that the directives occur many times in random contexts, so many of them don't really make sense. Keep in mind how to ensure that your cases are better. -.. exerciselist:: +:::{exerciselist} +::: diff --git a/content/figures.md b/content/figures.md new file mode 100644 index 0000000..b2ff717 --- /dev/null +++ b/content/figures.md @@ -0,0 +1,45 @@ +# Figures + +The `figure` directive inserts an image and also provides a caption +and other material. + +- The path is the relative or absolute path *within the sphinx source + directory*. +- You can give optional CSS classes, `with-border` gives it a black + border. Remove this if you don't want it - the examples below + include it. + +:::{figure} img/sample-image.png +:class: with-border + +This is the caption. +::: + +In ReST, this is: + +``` +.. figure:: img/sample-image.png + :class: with-border + + This is the caption. +``` + +In MyST Markdown, this is: + +```` +```{figure} img/sample-image.png +--- +class: with-border +--- + +This is the figure caption. +``` +```` + +When adding figures, optimize for narrow columns. First off, many +themes keep it in a small column but even if not, learners will +usually need to keep the text in a small column anyway, to share the +screen with their workspace. If you are `690` or less, then +sphinx_rtd_theme has no image scaling. `600` or less may be best. +If larger, then they may be scaled down (in some themes) or scroll +left (others). diff --git a/content/figures.rst b/content/figures.rst deleted file mode 100644 index ea96b06..0000000 --- a/content/figures.rst +++ /dev/null @@ -1,46 +0,0 @@ -Figures -======= - -The ``figure`` directive inserts an image and also provides a caption -and other material. - -* The path is the relative or absolute path *within the sphinx source - directory*. - -* You can give optional CSS classes, ``with-border`` gives it a black - border. Remove this if you don't want it - the examples below - include it. - -.. figure:: img/sample-image.png - :class: with-border - - This is the caption. - - -In ReST, this is:: - - .. figure:: img/sample-image.png - :class: with-border - - This is the caption. - - - -In MyST Markdown, this is:: - - ```{figure} img/sample-image.png - --- - class: with-border - --- - - This is the figure caption. - ``` - - -When adding figures, optimize for narrow columns. First off, many -themes keep it in a small column but even if not, learners will -usually need to keep the text in a small column anyway, to share the -screen with their workspace. If you are ``690`` or less, then -sphinx_rtd_theme has no image scaling. ``600`` or less may be best. -If larger, then they may be scaled down (in some themes) or scroll -left (others). diff --git a/content/getting-started.rst b/content/getting-started.md similarity index 52% rename from content/getting-started.rst rename to content/getting-started.md index bae2f00..cf7c96e 100644 --- a/content/getting-started.rst +++ b/content/getting-started.md @@ -1,35 +1,24 @@ -Getting started -=============== +# Getting started -From a template repository --------------------------- +## From a template repository You can get started by making a Sphinx project and configuring the extension. We recommend you use the sphinx-lesson-template repository -(https://github.com/coderefinery/sphinx-lesson-template). +(). This template repository is updated with new copies of base files as the lesson develops - you might want to check back for them, later. +## Convert an existing jekyll lesson +See {doc}`convert-old-lessons`. -Convert an existing jekyll lesson ---------------------------------- +## From scratch -See :doc:`convert-old-lessons`. - - - -From scratch ------------- - -See the next page, :doc:`installation`, for raw Python packages to +See the next page, {doc}`installation`, for raw Python packages to install and how to configure a arbitrary Sphinx project. - - -Github Pages initial commit ---------------------------- +## Github Pages initial commit The included Github Actions file will automatically push to Github Pages, but due to some quirk/bugs in gh-pages *the very first @@ -38,21 +27,20 @@ do one push yourself (or go to settings and disable-enable gh-pages the first time). You can make an empty commit to gh-pages this way, which will trigger -the gh-pages deployment (and everything will be automatic after that):: +the gh-pages deployment (and everything will be automatic after that): - git checkout -b gh-pages origin/gh-pages - git commit -m 'empty commit to trigger gh-pages' --allow-empty - git push +``` +git checkout -b gh-pages origin/gh-pages +git commit -m 'empty commit to trigger gh-pages' --allow-empty +git push +``` - -Demo lessons ------------- +## Demo lessons This guide can't currently stand alone. It is probably good to look at and copy from existing lessons for some things: -* Python for Scientific Computing uses many of the features: - https://aaltoscicomp.github.io/python-for-scicomp/ . - -* Github without the command line is a complete lesson using the - theme: https://coderefinery.github.io/github-without-command-line/ . +- Python for Scientific Computing uses many of the features: + . +- Github without the command line is a complete lesson using the + theme: . diff --git a/content/gh-action.md b/content/gh-action.md new file mode 100644 index 0000000..1f18536 --- /dev/null +++ b/content/gh-action.md @@ -0,0 +1,19 @@ +# Deployment with Github Actions + +In this repository, there is a `.github/workflows/sphinx.yml` file +that contains a Github Action that: + +- Installs dependencies + +- Builds the project with Sphinx + +- Deploys it + + - If branch = `master` (to be renamed to `main`), deploy to github pages normally + - For other branches, deploy to github-pages but put the result in + the `branch/{branch-name}` subdirectory. If the branch name has + a `/` in it, replace it with `--`. + - Keep all previous deployments, but remove branch subdirectories + for branches that no longer exist. + +This allows you to view builds from pull requests or other branches. diff --git a/content/gh-action.rst b/content/gh-action.rst deleted file mode 100644 index 9e0e002..0000000 --- a/content/gh-action.rst +++ /dev/null @@ -1,20 +0,0 @@ -Deployment with Github Actions ------------------------------- - -In this repository, there is a ``.github/workflows/sphinx.yml`` file -that contains a Github Action that: - -* Installs dependencies -* Builds the project with Sphinx -* Deploys it - - * If branch = ``master`` (to be renamed to ``main``), deploy to github pages normally - - * For other branches, deploy to github-pages but put the result in - the ``branch/{branch-name}`` subdirectory. If the branch name has - a ``/`` in it, replace it with ``--``. - - * Keep all previous deployments, but remove branch subdirectories - for branches that no longer exist. - -This allows you to view builds from pull requests or other branches. diff --git a/content/index.md b/content/index.md new file mode 100644 index 0000000..8decb32 --- /dev/null +++ b/content/index.md @@ -0,0 +1,98 @@ +# sphinx-lesson: structured lessons with Sphinx + +:::{seealso} +See a real demo lesson at +. +::: + +sphinx-lesson is a set of Sphinx extensions and themes for creating +interactive, hands-on lessons. It was originally made to replace the +CodeRefinery jekyll themes, but is designed to be used by others. + +As the name says, it is based on the [Sphinx documentation generator](https://www.sphinx-doc.org/). It is also inspired by and based on +[jupyter-book](https://jupyterbook.org/), but both is jupyter-book +and isn't. It *is* because jupyter-book is based on Sphinx and +modular, we reuse all of those same Sphinx extensions which +jupyter-book has made. It *isn't* jupyter-book because we configure +Sphinx directly, instead of wrapping it through jupyter-book +configuration and building. Thus, we get full control and high +compatibility. + +Features: + +- Separate content and presentation: easy to adjust theme or control + the parts independently. +- Based on jupyter-book, cross-compatible. +- Built with Sphinx, providing a structured, controlled output. +- Distributed as Python pip packages +- Markdown and ReStructured equally supported (yes, including all + directives), though ReStructured Text is still a bit nicer +- Jupyter notebooks as an input format. Can execute code (in jupyter + and other formats, too) +- Transparent transformation of jekyll-style markdown styles into + CommonMark with directives +- Also renders with sphinx-book-theme (theme of jupyterbook) ([preview](https://coderefinery.github.io/sphinx-lesson/branch/sphinx-book-theme/)) + +This is in an alpha state: we use it for lessons, but there is still +refinement work to go. + +:::{prereq} +- If you know Sphinx, it helps some. If not, it's easy to copy +- Markdown or ReStructured text +- Hosting is usually by github-pages +::: + +```{toctree} +:caption: Getting started +:maxdepth: 1 + +getting-started +installation +contributing-to-a-lesson +building +changelog +``` + +```{toctree} +:caption: Basic syntax +:maxdepth: 1 + +md-and-rst +toctree +directives +figures +``` + +```{toctree} +:caption: Examples +:maxdepth: 1 + +sample-episode-myst +sample-episode-rst +``` + +```{toctree} +:caption: Advanced features +:maxdepth: 1 + +intersphinx +md-transforms +jupyter +executing-code +substitutions-replacements +gh-action +presentation-mode +indexing +exercise-list +convert-old-lessons +``` + +```{toctree} +:caption: Extras +:maxdepth: 1 + +cheatsheet +``` + +- {ref}`genindex` +- {ref}`search` diff --git a/content/index.rst b/content/index.rst deleted file mode 100644 index f3a042d..0000000 --- a/content/index.rst +++ /dev/null @@ -1,99 +0,0 @@ -sphinx-lesson: structured lessons with Sphinx -============================================= - -.. seealso:: - - See a real demo lesson at - https://coderefinery.github.io/github-without-command-line/. - -sphinx-lesson is a set of Sphinx extensions and themes for creating -interactive, hands-on lessons. It was originally made to replace the -CodeRefinery jekyll themes, but is designed to be used by others. - -As the name says, it is based on the `Sphinx documentation generator -`__. It is also inspired by and based on -`jupyter-book `__, but both is jupyter-book -and isn't. It *is* because jupyter-book is based on Sphinx and -modular, we reuse all of those same Sphinx extensions which -jupyter-book has made. It *isn't* jupyter-book because we configure -Sphinx directly, instead of wrapping it through jupyter-book -configuration and building. Thus, we get full control and high -compatibility. - -Features: - -* Separate content and presentation: easy to adjust theme or control - the parts independently. -* Based on jupyter-book, cross-compatible. -* Built with Sphinx, providing a structured, controlled output. -* Distributed as Python pip packages -* Markdown and ReStructured equally supported (yes, including all - directives), though ReStructured Text is still a bit nicer -* Jupyter notebooks as an input format. Can execute code (in jupyter - and other formats, too) -* Transparent transformation of jekyll-style markdown styles into - CommonMark with directives -* Also renders with sphinx-book-theme (theme of jupyterbook) (`preview - `__) - -This is in an alpha state: we use it for lessons, but there is still -refinement work to go. - - -.. prereq:: - - * If you know Sphinx, it helps some. If not, it's easy to copy - * Markdown or ReStructured text - * Hosting is usually by github-pages - - -.. toctree:: - :maxdepth: 1 - :caption: Getting started - - getting-started - installation - contributing-to-a-lesson - building - changelog - -.. toctree:: - :maxdepth: 1 - :caption: Basic syntax - - md-and-rst - toctree - directives - figures - -.. toctree:: - :maxdepth: 1 - :caption: Examples - - sample-episode-rst - -.. toctree:: - :maxdepth: 1 - :caption: Advanced features - - intersphinx - md-transforms - jupyter - executing-code - substitutions-replacements - gh-action - presentation-mode - indexing - exercise-list - convert-old-lessons - -.. toctree:: - :maxdepth: 1 - :caption: Extras - - cheatsheet - - - -* :ref:`genindex` -* :ref:`search` diff --git a/content/indexing.md b/content/indexing.md new file mode 100644 index 0000000..7fc50d8 --- /dev/null +++ b/content/indexing.md @@ -0,0 +1,109 @@ +# Indexing + +An index lets you efficiently look up any topic. In the age of +full-text search, you are right to wonder what the point of indexes +are. They could be seen as companion of cheatsheet: instead of +searching and hoping you find the hright place, you can index the +actual locations to which one would refer. + +As you might expect, there is nothing special to in sphinx-lesson +about indexing: see the Sphinx documentation on {rst:dir}`index`. + +```{index} ! Index +``` + +## Basic concepts + +**Headings** are the terms which can be looked up in the index. When +choosing headings, consider: + +- What is useful to a reader to locate +- How would a reader look it up? For example, `commit` or + `committing` is useful, but `how to commit` is not. Phrase it + with the most important terms first (big-endian) +- And index can have sub-entries. For example, under the entry + `git`, there can be subentries for each git command, such as + `commit`. + +## Syntax + +:::{seealso} +The Sphinx documentation on {rst:dir}`index`. +::: + +```{highlight} rst +``` + +The `index` directive and role are the main ways to add index +entries. The semicolon (`;`) character separates entries and +subentries. + +```{index} pair: index; ReST +``` + +Index a block with the directive, with ReST: + +``` +.. index:: commit; amend +``` + +Or ReST, multiple: + +``` +.. index:: + commit + commit; message + pair: commit; amend +``` + +MyST: + +```` +```{index} commit; amend +``` + +```{index} +commit +commit; mesage +pair: commit; amend +``` +```` + +Or index a single term with the role: + +``` +This sentence has an index entry for :index:`commit`. If you want the +indexed term to be different, standard syntax applies such as +:index:`loop variables `. +``` + +```{index} pair: index; MyST +``` + +MyST: + +``` +Simple entry: {index}`commit` +Pair entry: {index}`loop variables ` +``` + +```{index} index; single index; pair index; see index; seealso +``` + +There are different styles: + +- `TERM`, same as below +- `single: TERM` (the default): create just a single entry +- `pair: TERM; TERM`: create entries for `x; y` and `y; x` +- `see: TOPIC; OTHER`: creates a "see other" entry for "topic". +- `seealso: TOPIC; OTHER`: creates a "seealso" entry, like above + +## Glossaries + +If you make a glossary using the {rst:dir}`glossary directive +`, the terms automatically get added to the index + +## See also + +- {rst:dir}`index` directive +- Sphinx {rst:dir}`glossary` diff --git a/content/indexing.rst b/content/indexing.rst deleted file mode 100644 index 97886d2..0000000 --- a/content/indexing.rst +++ /dev/null @@ -1,116 +0,0 @@ -Indexing -======== - -An index lets you efficiently look up any topic. In the age of -full-text search, you are right to wonder what the point of indexes -are. They could be seen as companion of cheatsheet: instead of -searching and hoping you find the hright place, you can index the -actual locations to which one would refer. - -As you might expect, there is nothing special to in sphinx-lesson -about indexing: see the Sphinx documentation on :rst:dir:`index`. - -.. index:: ! Index - -Basic concepts --------------- - -**Headings** are the terms which can be looked up in the index. When -choosing headings, consider: - -* What is useful to a reader to locate -* How would a reader look it up? For example, ``commit`` or - ``committing`` is useful, but ``how to commit`` is not. Phrase it - with the most important terms first (big-endian) -* And index can have sub-entries. For example, under the entry - ``git``, there can be subentries for each git command, such as - ``commit``. - - - -Syntax ------- - -.. seealso:: - - The Sphinx documentation on :rst:dir:`index`. - -.. highlight:: rst - -The ``index`` directive and role are the main ways to add index -entries. The semicolon (``;``) character separates entries and -subentries. - -.. index:: - pair: index; ReST - - -Index a block with the directive, with ReST:: - - .. index:: commit; amend - -Or ReST, multiple:: - - .. index:: - commit - commit; message - pair: commit; amend - - -MyST:: - - ```{index} commit; amend - ``` - - ```{index} - commit - commit; mesage - pair: commit; amend - ``` - - -Or index a single term with the role:: - - This sentence has an index entry for :index:`commit`. If you want the - indexed term to be different, standard syntax applies such as - :index:`loop variables `. - - -.. index:: - pair: index; MyST - -MyST:: - - Simple entry: {index}`commit` - Pair entry: {index}`loop variables ` - - -.. index:: - index; single - index; pair - index; see - index; seealso - -There are different styles: - -* ``TERM``, same as below -* ``single: TERM`` (the default): create just a single entry -* ``pair: TERM; TERM``: create entries for ``x; y`` and ``y; x`` -* ``see: TOPIC; OTHER``: creates a "see other" entry for "topic". -* ``seealso: TOPIC; OTHER``: creates a "seealso" entry, like above - - - -Glossaries ----------- - -If you make a glossary using the :rst:dir:`glossary directive -`, the terms automatically get added to the index - - - -See also --------- - -* :rst:dir:`index` directive -* Sphinx :rst:dir:`glossary` diff --git a/content/installation.md b/content/installation.md new file mode 100644 index 0000000..2672108 --- /dev/null +++ b/content/installation.md @@ -0,0 +1,50 @@ +# Installation + +## Sphinx Python package + +This is distributed as a normal Sphinx extension, so it is easy to +use. To use it, install `sphinx_lesson` via PyPI. + +Then, enable the extension in your Sphinx `conf.py`. This will both +define our special directives, and load the other required extensions +(`myst_nb`). The `myst_nb` extension can be configured normally: + +``` +extensions = [ + 'sphinx_lesson', +] +``` + +## HTML theme + +We are in theory compatible with any theme, but are most tested with +the sphinx_rtd_theme (which you need to set yourself): + +``` +html_theme = 'sphinx_rtd_theme' +``` + +The Jupyter Book (Executable Books Project) Sphinx theme +([sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/en/latest/)) has some +very nice features and also deserves some consideration. Using it +should be clear: `html_theme = "sphinx_book_theme"`. You can see a +preview of it [as a branch on github-pages](https://coderefinery.github.io/sphinx-lesson/branch/sphinx-book-theme/). + +## Under the hood + +Adding `sphinx_lesson` as an extension adds these sub-extensions: + +> - `sphinx_lesson.directives` - see {doc}`directives`. +> - `sphinx_lesson.md_transforms` - see {doc}`md-transforms`. +> - `sphinx_lesson.exerciselist` - see {doc}`exercise-list`. +> - `sphinx_lesson.term_role_formatting` - makes glossary term +> references bold +> - Enables the [myst_notebook extension](https://myst-nb.readthedocs.io/en/latest/), which also enables +> [myst_parser](https://myst-parser.readthedocs.io/en/latest/index.html) +> (included as a dependencies) +> - Enables the [sphinx-copybutton extension](https://github.com/executablebooks/sphinx-copybutton) +> (included as a dependency) +> - Same for [sphinx-tabs](https://sphinx-tabs.readthedocs.io/) +> - Same for [sphinx-togglebutton](https://pypi.org/project/sphinx-togglebutton/) + +Any of these can be used independently to get the same effect. diff --git a/content/installation.rst b/content/installation.rst deleted file mode 100644 index 45678c5..0000000 --- a/content/installation.rst +++ /dev/null @@ -1,57 +0,0 @@ -Installation -============ - -Sphinx Python package ---------------------- - -This is distributed as a normal Sphinx extension, so it is easy to -use. To use it, install ``sphinx_lesson`` via PyPI. - -Then, enable the extension in your Sphinx ``conf.py``. This will both -define our special directives, and load the other required extensions -(``myst_nb``). The ``myst_nb`` extension can be configured normally:: - - extensions = [ - 'sphinx_lesson', - ] - -HTML theme ----------- - -We are in theory compatible with any theme, but are most tested with -the sphinx_rtd_theme (which you need to set yourself):: - - html_theme = 'sphinx_rtd_theme' - -The Jupyter Book (Executable Books Project) Sphinx theme -(`sphinx-book-theme -`__) has some -very nice features and also deserves some consideration. Using it -should be clear: ``html_theme = "sphinx_book_theme"``. You can see a -preview of it `as a branch on github-pages -`__. - - - -Under the hood --------------- - -Adding ``sphinx_lesson`` as an extension adds these sub-extensions: - - * ``sphinx_lesson.directives`` - see :doc:`directives`. - * ``sphinx_lesson.md_transforms`` - see :doc:`md-transforms`. - * ``sphinx_lesson.exerciselist`` - see :doc:`exercise-list`. - * ``sphinx_lesson.term_role_formatting`` - makes glossary term - references bold - * Enables the `myst_notebook extension - `__, which also enables - `myst_parser - `__ - (included as a dependencies) - * Enables the `sphinx-copybutton extension - `__ - (included as a dependency) - * Same for `sphinx-tabs `__ - * Same for `sphinx-togglebutton `__ - -Any of these can be used independently to get the same effect. diff --git a/content/intersphinx.md b/content/intersphinx.md new file mode 100644 index 0000000..b876e09 --- /dev/null +++ b/content/intersphinx.md @@ -0,0 +1,88 @@ +# Intersphinx: easy linking + +There is a common problem: you want to link to documentation in other +sites, for example the documentation of `list.sort`. Isn't it nice +to have a structured way to do this so you don't have to a) look up a +URL yourself b) risk having links break? Well, what do you know, +Sphinx has a native solution for this: {py:mod}`Intersphinx +`. + +## Enable the extension + +It's built into Sphinx, and in the sphinx-lesson-template `conf.py` but +commented out. Enable it: + +```python +extensions.append('sphinx.ext.intersphinx') +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + } +``` + +Configuration details and how to link to other sites are found at +{py:mod}`the docs for intersphinx `. +For most Sphinx-documented projects, use the URL of the documentation +base. See "Usage" below for how to verify the URLs. + +## Usage + +Just like `:doc:` is a structured way to link to other documents, +there are other **domains** of links, such as `:py:class:`, +`:py:meth:`, and so on. So we can link to documentation of a class +or method like this: + +:::{admonition} Rendered (note the links) +The {py:class}`list` class {py:meth}`sort ` method. +::: + +```rst +# Restructured Text +The :py:class:`list` class :py:meth:`sort ` method. +``` + +```md +# MyST markdown +The {py:class}`list` class {py:meth}`sort ` method. +``` + +Note that this is structured information, and thus has no concept in +Markdown, only MyST "markdown". This is, in fact, a major reason why +plain markdown is hardly suitable for serious documentation. + +## Available linking domains and roles + +Of course, the domains are extendable. Presumably, when you use +sphinx-lesson, you will be referring to other things. The most +common roles in the Python domain are: + +- `:py:mod:`: modules, e.g. {py:mod}`multiprocessing` +- `:py:func:`: modules, e.g. {py:func}`itertools.combinations` +- `:py:class:`: modules, e.g. {py:class}`list` +- `:py:meth:`: modules, e.g. {py:meth}`list.sort` +- `:py:attr:`: modules, e.g. {py:attr}`re.Pattern.groups` +- `:py:data:`: modules, e.g. {py:data}`datetime.MINYEAR` +- Also `:py:exc:`, `:py:data:`, `:py:obj:`, `::`, `::` +- There are also built-in domains for C, C++, JavaScript (see + [the info on Sphinx domains](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) for what the roles are). + Others are added by Sphinx extensions. + +You can list all available reference targets at some doc using a +command line command. You can get the URL from the conf.py file (and +use this to verify URLs before you put it in the conf.py file): + +```shell +# Note we need to append `objects.inv`: +python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv +# In conf.py: 'python': ('https://docs.python.org/3', None), +``` + +You usually use the fully qualified name of an object, for example +`matplotlib.pyplot.plot`. In Python this is usually pretty obvious, +due to clear namespacing. You'll have to look at other languages +yourself. + +## See also + +- [Sphinx: domains](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) - how to + document classes/functions to be referrable this way, and link to them. +- {py:mod}`Intersphinx `. diff --git a/content/intersphinx.rst b/content/intersphinx.rst deleted file mode 100644 index f454ff2..0000000 --- a/content/intersphinx.rst +++ /dev/null @@ -1,99 +0,0 @@ -Intersphinx: easy linking -========================= - -There is a common problem: you want to link to documentation in other -sites, for example the documentation of ``list.sort``. Isn't it nice -to have a structured way to do this so you don't have to a) look up a -URL yourself b) risk having links break? Well, what do you know, -Sphinx has a native solution for this: :py:mod:`Intersphinx -`. - - - -Enable the extension --------------------- -It's built into Sphinx, and in the sphinx-lesson-template ``conf.py`` but -commented out. Enable it: - -.. code-block:: python - - extensions.append('sphinx.ext.intersphinx') - intersphinx_mapping = { - 'python': ('https://docs.python.org/3', None), - } - -Configuration details and how to link to other sites are found at -:py:mod:`the docs for intersphinx `. -For most Sphinx-documented projects, use the URL of the documentation -base. See "Usage" below for how to verify the URLs. - - -Usage ------ - -Just like ``:doc:`` is a structured way to link to other documents, -there are other **domains** of links, such as ``:py:class:``, -``:py:meth:``, and so on. So we can link to documentation of a class -or method like this: - -.. admonition:: Rendered (note the links) - - The :py:class:`list` class :py:meth:`sort ` method. - -.. code-block:: rst - - # Restructured Text - The :py:class:`list` class :py:meth:`sort ` method. - -.. code-block:: md - - # MyST markdown - The {py:class}`list` class {py:meth}`sort ` method. - -Note that this is structured information, and thus has no concept in -Markdown, only MyST "markdown". This is, in fact, a major reason why -plain markdown is hardly suitable for serious documentation. - - - -Available linking domains and roles ------------------------------------ - -Of course, the domains are extendable. Presumably, when you use -sphinx-lesson, you will be referring to other things. The most -common roles in the Python domain are: - -* ``:py:mod:``: modules, e.g. :py:mod:`multiprocessing` -* ``:py:func:``: modules, e.g. :py:func:`itertools.combinations` -* ``:py:class:``: modules, e.g. :py:class:`list` -* ``:py:meth:``: modules, e.g. :py:meth:`list.sort` -* ``:py:attr:``: modules, e.g. :py:attr:`re.Pattern.groups` -* ``:py:data:``: modules, e.g. :py:data:`datetime.MINYEAR` -* Also ``:py:exc:``, ``:py:data:``, ``:py:obj:``, ``::``, ``::`` -* There are also built-in domains for C, C++, JavaScript (see - `the info on Sphinx domains `__ for what the roles are). - Others are added by Sphinx extensions. - -You can list all available reference targets at some doc using a -command line command. You can get the URL from the conf.py file (and -use this to verify URLs before you put it in the conf.py file): - -.. code-block:: shell - - # Note we need to append `objects.inv`: - python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv - # In conf.py: 'python': ('https://docs.python.org/3', None), - -You usually use the fully qualified name of an object, for example -``matplotlib.pyplot.plot``. In Python this is usually pretty obvious, -due to clear namespacing. You'll have to look at other languages -yourself. - - - -See also --------- - -* `Sphinx: domains `__ - how to - document classes/functions to be referrable this way, and link to them. -* :py:mod:`Intersphinx `. diff --git a/content/md-and-rst.md b/content/md-and-rst.md new file mode 100644 index 0000000..44a3331 --- /dev/null +++ b/content/md-and-rst.md @@ -0,0 +1,155 @@ +# Markdown and ReST + +Sites can be written in Markdown on ReStructured Text. Actually, in +theory any format that has a Sphinx parser could be used, however you +will be slightly limited without directive support. + +## Markdown + +Let's start off with a basic fact: Markdown isn't a language. It's +some html-like markup that is not structured enough for the purposes +of structured sites such as sphinx-lesson. There are many different +flavors, some of which add extra syntax which gets it closer to +enough, but for our purposes these are different enough that they +should count as different languages (as similar as "markdown" and +ReST). Since the Markdown creator says that [Markdown shouldn't +evolve or be strictly defined](https://en.wikipedia.org/wiki/Markdown#CommonMark), Markdown is +essentially a dead syntax: you should always specific which living +sub-syntax you are referring to. + +sphinx-lesson uses the [MyST-parser] (markedly structured text), +which is both completely compatible with CommonMark, and also supports +*all ReStructured Text directives*, unlike most other non-ReST Sphinx +parsers. Thus, we finally have a way to write equivalent ReST and +Markdown without any compromises (though other CommonMark parsers +aren't expected to know Sphinx directives). + +[MyST syntax reference](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) + +## ReStructured Text + +ReStructured Text has native support for roles and directives, which +makes it a more structured language such as LaTeX, rather than HTML. + +[ReST reference (from Sphinx)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) + +## MD and ReST syntax + +This is a brief comparison of basic syntax: + +ReST syntax (Sphinx has a good [restructured text primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html): + +```rst +*italic* +**bold** +``literal`` + +Heading +------- + +`inline link `__ +`out-of-line link `__ + +.. _example: https://example.com + +:doc:`page-filename` +:ref:`ref-name` +:py:mod:`multiprocessing` + +:doc:`link to page ` +:ref:`page anchor link ` +:py:mod:`intersphinx link ` + + +:: + + code block that is standalone (two + colons before it and indented) + +Code block after paragraph:: + + The paragraph will end with + a single colon. +``` + +MyST markdown syntax: + +````md +*italic* +**bold** +`literal` +# Heading + +[inline link](https://example.com) + +[link to page](relative-page-path) + +``` +code block +``` +```` + +The most interesting difference is the use of single backquote for +literals in Markdown, and double in ReST. This is because ReST uses +single quotes for *roles* - notice how there is a dedicated syntax for +inter-page links, references, and so on. This is very important for +things like verifying referential integrity of all of our pages. But +this is configurable with [default_role](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-default_role): +set to `any` to automatically detect documents/references/anthing, +or `literal` to automatically be the same as literal text. + +## Directives + +A core part of any Sphinx site is the directives: this provides +structured parsing for blocks of text. For example, we have an +`exercise` directive, which formats a text block into an exercise +callout. This is not just a CSS class, it can do anything during the +build phase (but in practice we don't do such complex things). + +### ReST directives + +ReST directives are done like this: + +```rst +.. exercise:: Optional title, some default otherwise + :option: value + + This is the body + + You can put *arbitrary syntax* here. +``` + +### MyST directives + +MyST-parser directives are done like this: + +````md +```{exercise} +:option: value + +content +``` +```` + +## Roles + +Roles are for inline text elements. A lot like directives, they can +be as simple as styling or do arbitrary transformations in Python. + +### ReST roles + +Like this: + +```rst +:rolename:`interpreted text` +``` + +### MyST roles + +Like this: + +```md +{rolename}`interpreted text` +``` + +[myst-parser]: https://github.com/executablebooks/myst-parser diff --git a/content/md-and-rst.rst b/content/md-and-rst.rst deleted file mode 100644 index 7c29b1a..0000000 --- a/content/md-and-rst.rst +++ /dev/null @@ -1,178 +0,0 @@ -Markdown and ReST -================= - -Sites can be written in Markdown on ReStructured Text. Actually, in -theory any format that has a Sphinx parser could be used, however you -will be slightly limited without directive support. - - - -Markdown --------- - -Let's start off with a basic fact: Markdown isn't a language. It's -some html-like markup that is not structured enough for the purposes -of structured sites such as sphinx-lesson. There are many different -flavors, some of which add extra syntax which gets it closer to -enough, but for our purposes these are different enough that they -should count as different languages (as similar as "markdown" and -ReST). Since the Markdown creator says that `Markdown shouldn't -evolve or be strictly defined -`__, Markdown is -essentially a dead syntax: you should always specific which living -sub-syntax you are referring to. - -sphinx-lesson uses the `MyST-parser`_ (markedly structured text), -which is both completely compatible with CommonMark, and also supports -*all ReStructured Text directives*, unlike most other non-ReST Sphinx -parsers. Thus, we finally have a way to write equivalent ReST and -Markdown without any compromises (though other CommonMark parsers -aren't expected to know Sphinx directives). - -.. _MyST-parser: https://github.com/executablebooks/myst-parser - -`MyST syntax reference `__ - - -ReStructured Text ------------------ - -ReStructured Text has native support for roles and directives, which -makes it a more structured language such as LaTeX, rather than HTML. - -`ReST reference (from Sphinx) `__ - - -MD and ReST syntax ------------------- - -This is a brief comparison of basic syntax: - -ReST syntax (Sphinx has a good `restructured text primer -`__: - -.. code:: rst - - *italic* - **bold** - ``literal`` - - Heading - ------- - - `inline link `__ - `out-of-line link `__ - - .. _example: https://example.com - - :doc:`page-filename` - :ref:`ref-name` - :py:mod:`multiprocessing` - - :doc:`link to page ` - :ref:`page anchor link ` - :py:mod:`intersphinx link ` - - - :: - - code block that is standalone (two - colons before it and indented) - - Code block after paragraph:: - - The paragraph will end with - a single colon. - - -MyST markdown syntax: - -.. code:: md - - *italic* - **bold** - `literal` - # Heading - - [inline link](https://example.com) - - [link to page](relative-page-path) - - ``` - code block - ``` - -The most interesting difference is the use of single backquote for -literals in Markdown, and double in ReST. This is because ReST uses -single quotes for *roles* - notice how there is a dedicated syntax for -inter-page links, references, and so on. This is very important for -things like verifying referential integrity of all of our pages. But -this is configurable with `default_role -`__: -set to ``any`` to automatically detect documents/references/anthing, -or ``literal`` to automatically be the same as literal text. - - - -Directives ----------- - -A core part of any Sphinx site is the directives: this provides -structured parsing for blocks of text. For example, we have an -``exercise`` directive, which formats a text block into an exercise -callout. This is not just a CSS class, it can do anything during the -build phase (but in practice we don't do such complex things). - -ReST directives -~~~~~~~~~~~~~~~ - -ReST directives are done like this: - -.. code:: rst - - .. exercise:: Optional title, some default otherwise - :option: value - - This is the body - - You can put *arbitrary syntax* here. - -MyST directives -~~~~~~~~~~~~~~~ - -MyST-parser directives are done like this: - -.. code:: md - - ```{exercise} - :option: value - - content - ``` - - - -Roles ------ - -Roles are for inline text elements. A lot like directives, they can -be as simple as styling or do arbitrary transformations in Python. - -ReST roles -~~~~~~~~~~ - -Like this: - -.. code:: rst - - :rolename:`interpreted text` - -MyST roles -~~~~~~~~~~ - -Like this: - -.. code:: md - - {rolename}`interpreted text` - diff --git a/content/presentation-mode.rst b/content/presentation-mode.md similarity index 56% rename from content/presentation-mode.rst rename to content/presentation-mode.md index 7b77d50..eaa9ee5 100644 --- a/content/presentation-mode.rst +++ b/content/presentation-mode.md @@ -1,15 +1,14 @@ -Presentation mode -================= +# Presentation mode -.. note:: +:::{note} +This is a technical demo, included by default to make it easy to +use. It may be removed in a future release. +::: - This is a technical demo, included by default to make it easy to - use. It may be removed in a future release. - -Using `minipres `__, +Using [minipres](https://github.com/coderefinery/sphinx-minipres), any web page can be turned into a presentation. As usual, there is nothing very specific to sphinx-lesson about this, but currently -minipres is only tested on ``sphinx_rtd_theme``, but theoretically can +minipres is only tested on `sphinx_rtd_theme`, but theoretically can work on others. Using minipres, you only have to write one page: the material your @@ -20,20 +19,21 @@ presentation and the readability of a single page. How it works: -- Add ``?minipres`` to the URL of any page, and it goes into +- Add `?minipres` to the URL of any page, and it goes into presentation mode. -- Add ``?plain`` to the URL of any page to go to plain mode. +- Add `?plain` to the URL of any page to go to plain mode. In presentation mode: - The sidebars are removed (this is the only thing that happens in - ``plain`` mode). + `plain` mode). - Extra space is added between each section (HTML headings), so that you focus on one section at a time - The **left/right arrow keys** scroll between sections. Examples: -* `View this page as an example of minipres - <../sample-episode-rst/?minipres>`__. -* `View this page in "plain" mode <../sample-episode-rst/?plain>`__. +```{eval-rst} +- `View this page as an example of minipres <../sample-episode-rst/?minipres>`__. +- `View this page in "plain" mode <../sample-episode-rst/?plain>`__. +``` diff --git a/content/sample-episode-myst.md b/content/sample-episode-myst.md new file mode 100644 index 0000000..b72d2b6 --- /dev/null +++ b/content/sample-episode-myst.md @@ -0,0 +1,267 @@ +# Sample episode in MyST (Markdown) + +:::{questions} +- What syntax is used to make a lesson? +- How do you structure a lesson effectively for teaching? + +`questions` are at the top of a lesson and provide a starting +point for what you might learn. It is usually a bulleted list. +(The history is a holdover from carpentries-style lessons, and is +not required.) +::: + +:::{objectives} +- Show a complete lesson page with all of the most common + structures. + +- ... + +This is also a holdover from the carpentries-style. It could +usually be left off. +::: + +A first paragraph really motivating *why* you would need the material +presented on this page, and why it is exciting. Don't go into details. + +Then, another paragraph going into the big picture of *what* you will +do and *how* you will do it. Not details, but enough so that someone +knows the overall path. + +\[For the syntax of ReST, you really want to browse this page alongside the +source of it, to see how this is implemented. See the links at the to +right of the page.\] + +## Section titles should be enough to understand the page + +The first paragraph of each section should again summarize what you +will do in it. + +Top-level section titles are the map through the page and should make +sense together. + +This is text. + +A code block with preceeding paragraph: + +``` +import multiprocessing +``` + +- A bullet list + +- Bullet list + + - Sub-list: + + ``` + code block (note indention) + ``` + + :::{note} + directive within a list (note indention) + ::: + +````{tabs} +```{code-tab} py +import bisect +a = 1 + 2 +``` + +```{code-tab} r R +library(x) +a <- 1 + 2 +``` +```` + +:::{discussion} This is a `discussion` directive +Discussion content. +::: + +## Exercise: \[the general topic\] + +These exercises will show basic exercise conventions. It might be +useful for the first paragraph of a multi-exercise section to tie them +together to the overall point, but that isn't necessary. + +\[Exercises get their own section, so that they can be linked and found +in the table of contents.\] + +:::{exercise} ReST-1 Imperative statement of what will happen in the exercise. +An intro paragraph about the exercise, if not obvious. Expect that +learners and exercise leaders will end up here without having +browsed the lesson above. Make sure that they understand the +general idea of what is going on and *why* the exercise exists +(what the learning objective is roughly, for example there is a big +difference between making a commit and focusing on writing a good +commit message and knowing the command line arguments!) + +1. Bullet list if multiple parts. + +2. Despite the names, most exercises are not really "exercises" in + that the are difficult. Most are rather direct applications of + what has been learned (unless they are `(advanced)`). + +3. When writing the exercise steps, try to make it clear enough + that a helper/exercise leader who knows the general tools + somewhat well (but doesn't know the lesson) can lead the + exercise just by looking at the text in the box. + + - Of course that's not always possible, sometimes they actually + are difficult. +::: + +:::{solution} +- Solution here. +::: + +:::{exercise} (optional) ReST-2 Imperative statement of what will happen in the exercise. +1. Optional exercises are prefixed with `(optional)` +2. It's better to have more exercises be optional than many that + are made optional ad-hoc. Every instructor may do something + different, but it's better to seem like you are covering all the + main material than seem like you are skipping parts. +::: + +:::{solution} +- Solution to that one. +::: + +::::{exercise} (optional) ReST-3: Exercise with embedded solution +1. This exercise has the solution within its box itself. This is a + stylistic difference more than anything. + +:::{solution} +- Solution to that one. +::: +:::: + +:::{exercise} (advanced) ReST-4: Exercise with embedded solution +1. `(advanced)` is the tag for things which really require + figuring out stuff on your own. Can also be `(advanced, + optional)` but that's sort of implied. +2. This also demonstrates an exercise with a {doc}`link `, + or {ref}`internal reference `. +::: + +## This entire section is an exercise + +:::{admonition} Exercise leader setup +:class: dropdown + +This admonition is a drop-down and can be used for instructor or +exercise-leader specific setup. (see also / compare with +`instructor-note`. +::: + +:::{exercise} In this section, we will \[do something\] +Standard intro paragraph of the exercise. + +Describe how this exercise is following everything that is in this +section. +::: + +Do this. + +Then do that. + +And so on. + +## Another section + +:::{instructor-note} +This is an instructor note. It may be hidden, collapsed, or put to +the sidebar in a later style. You should use it for things that +the instructor should see while teaching, but should be +de-emphasized for the learners. Still, we don't hide them for +learners (instructors often present from the same view.) +::: + +These tab synchronize with those above: + +````{tabs} +```{code-tab} py +import cmath +a = 10 / 2 +``` + +```{code-tab} r R +library(x) +a <- 10 / 2 +``` +```` + +:::{admonition} Advanced info that should be hidden +:class: dropdown + +Any advanced information can be hidden behind any admonition by +adding a `dropdown` class to it (syntax: `:class: dropdown` as +first line separated by a space). + +This can be useful for advanced info that should not be show in the +main body of text.. +::: + +### A subsection + +Subsections are fine, use them as you want. But make sure the main +sections tell the story and provide a good table of contents to the +episode. + +:::{figure} img/sample-image.png +Figure caption here. +::: + +:::{figure} img/sample-image.png +:class: with-border + +Figure caption here, which explains the content in text so that +it's accessible to screen readers. +::: + +## Other directives + +:::{seealso} +A reference to something else. Usually used at the top of a +section or page to highlight that the main source of information is +somewhere else. Regular-importance "see also" is usually at a +section at the bottom of the page or an a regular paragraph text. +::: + +:::{important} +This is used for things that should be highlighted to prevent +significant confusion. It's not *that* often used. +::: + +:::{warning} +Something which may result in data loss, security, or massive +confusion. It's not *that* often used. +::: + +## What's next? + +Pointers to what someone can learn about next to expand on this topic, +if relevant. + +## Summary + +A summary of what you learned. + +## See also + +A "see also" section is good practice to show that you have researched +the topic well and your lesson becomes a hub pointing to the other +best possible resources. + +- Upstream information +- Another course + +:::{keypoints} +- What the learner should take away + +- point 2 + +- ... + +This is another holdover from the carpentries style. This perhaps +is better done in a "summary" section. +::: diff --git a/content/sample-episode-rst.rst b/content/sample-episode-rst.rst index 9953532..c8a9232 100644 --- a/content/sample-episode-rst.rst +++ b/content/sample-episode-rst.rst @@ -143,7 +143,7 @@ in the table of contents.] figuring out stuff on your own. Can also be ``(advanced, optional)`` but that's sort of implied. 2. This also demonstrates an exercise with a :doc:`link `, - or :ref:`internal reference `. + or :ref:`internal reference `. diff --git a/content/substitutions-replacements.rst b/content/substitutions-replacements.md similarity index 75% rename from content/substitutions-replacements.rst rename to content/substitutions-replacements.md index 67fb406..ca9b917 100644 --- a/content/substitutions-replacements.rst +++ b/content/substitutions-replacements.md @@ -1,6 +1,4 @@ -Substitutions and replacement variables -======================================= - +# Substitutions and replacement variables Like most languages, ReST and MyST both have direct ways to substitute variables to locally customize lessons. While this works for simple @@ -8,8 +6,7 @@ cases, this can quickly become difficult to manage with the "master copy" of possibly important content being separated from the main body, and keeping the substitutions up to date. -`sphinx_ext_substitution -`__ tries to +[sphinx_ext_substitution](https://github.com/NordicHPC/sphinx_ext_substitution) tries to solve these problems by keeping the default values within the document and providing tools to manage the substitution as the context changes over time. It is tested with ReST and should work with MyST as well. diff --git a/content/toctree.rst b/content/toctree.md similarity index 52% rename from content/toctree.rst rename to content/toctree.md index 8baa757..9b4096f 100644 --- a/content/toctree.rst +++ b/content/toctree.md @@ -1,40 +1,42 @@ -Table of Contents tree -====================== +# Table of Contents tree Pages are not found by globbing a pattern: you can explicitly define a table of contents list. There must be one master toctree in the index document, but then they can be nested down. For the purposes of sphinx-lesson, we probably don't need such features -ReST:: - - .. toctree:: - caption: Episodes - maxdepth: 1 - - basics - creating-using-web - creating-using-desktop - contributing - doi - websites - - -MyST:: - - ```{toctree} - --- - caption: Episodes - maxdepth: 1 - --- - - basics - creating-using-web - creating-using-desktop - contributing - doi - websites - ``` +ReST: + +``` +.. toctree:: +caption: Episodes +maxdepth: 1 + +basics +creating-using-web +creating-using-desktop +contributing +doi +websites +``` + +MyST: + +```` +```{toctree} +--- +caption: Episodes +maxdepth: 1 +--- + +basics +creating-using-web +creating-using-desktop +contributing +doi +websites +``` +```` The pages are added by filename (no extension needed). The name by default comes from the document title, but you can override it if you @@ -44,10 +46,6 @@ You can have multiple toctrees: check sphinx-test-lesson, we have one for the episodes, and one for extra material (like quick ref and instructor guide). +## See also -See also --------- - -* Read more about the `Sphinx toctree directive`__. - -__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents +- Read more about the [Sphinx toctree directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents).