Merge pull request coderefinery#104 from coderefinery/rkdarst/various…

…-revisions Emphasize MyST, various other improvements
ENCCS · Aug 12, 2024 · d640423 · d640423
2 parents d6da11f + 04e8204
commit d640423
Show file tree

Hide file tree

Showing 19 changed files with 225 additions and 132 deletions.
diff --git a/content/building.md b/content/building.md
@@ -1,14 +1,24 @@
 # Building the lesson
 
-It is built the normal Sphinx way:
+```{highlight} console
+```
+
+It is built the normal Sphinx ways.  Using Sphinx directly, one would
+run:
+
+```
+$ sphinx-build -M html content/ _build
+```
+
+If you have `make` installed, you can:
 
 ```
-make html
-# or
-make dirhtml
-# full build
-make clean html
+$ 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/`.
+However, there are different ways to set up a Sphinx project.
+CodeRefinery lessons puts the results in `_build/`.
diff --git a/content/changelog.md b/content/changelog.md
@@ -1,5 +1,8 @@
 # Changelog
 
+This isn't very up to date right now.  There haven't been significant
+backwards-incompatible changes, so this hasn't been kept in earnest.
+
 ## 0.8.0
 
 - First PyPI release
diff --git a/content/cheatsheet.md b/content/cheatsheet.md
@@ -1,3 +1,6 @@
 # Cheatsheet
 
-This is the cheatsheet.
+Nothing here yet.  See the sample episodes:
+
+* [MyST markdown](https://github.com/coderefinery/sphinx-lesson/blob/master/content/sample-episode-myst.md?plain=1)
+* [ReST](https://github.com/coderefinery/sphinx-lesson/blob/master/content/sample-episode-rst.rst?plain=1)
diff --git a/content/conf.py b/content/conf.py
@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Sphinx-lesson'
-copyright = '2020, CodeRefinery'
+copyright = '2020-2024, CodeRefinery'
 author = 'CodeRefinery'
 
 # roundabout way to get version.  "import sphinx_lesson" would be easier, but
@@ -47,6 +47,9 @@
     'sphinx_rtd_theme_ext_color_contrast',
 ]
 
+# Sphinx-lesson config:
+sphinx_lesson_transform_html_img = False
+
 # Settings for myst_nb:
 # https://myst-nb.readthedocs.io/en/latest/computation/execute.html#notebook-execution-modes
 #nb_execution_mode = "off"

diff --git a/content/contributing-to-a-lesson.md b/content/contributing-to-a-lesson.md
@@ -9,10 +9,11 @@ is fairly easy:
 - (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.
+In summary, each lesson is like a Python project, with the lesson
+content as its documentation in the `content/` directory (and no
+Python code).  Everything is fairly standard: 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.
@@ -35,7 +36,7 @@ $ git clone git://github.com/ORGANIZATION/LESSON.git
 ## Edit the material
 
 The material is in the `content/` directory.  Depending on the
-lesson, in may be in ReStructured Text, MyST Markdown, or Jupyter
+lesson, in may be in MyST Markdown, ReStructured Text, or Jupyter
 notebooks.
 
 ### ReStructured Text and MyST Markdown
@@ -47,10 +48,10 @@ this is not unstructured Markdown, but there are particular
 text.  (In fact, "markdown" is a broad concept and everyone uses some
 different extensions of it).
 
+- {doc}`sphinx-lesson directives for markup <directives>`
 - {doc}`md-and-rst`
-- {ref}`ReStructured Text reference <sphinx:rst-primer>`
 - [MyST reference](https://myst-parser.readthedocs.io/en/latest/using/syntax.html)
-- {doc}`sphinx-lesson directives for markup <directives>`
+- {ref}`ReStructured Text reference <sphinx:rst-primer>`
 
 *Do not worry about getting syntax right*.  Send your improvement, and
 editing is easy and you will learn something.

diff --git a/content/convert-old-lessons.md b/content/convert-old-lessons.md
@@ -1,5 +1,8 @@
 # Converting an old lesson
 
+**This was the old CodeRefinery procedure.  It is now unmaintained
+but might be useful for someone.  Let us know if you need it revived.**
+
 % highlight: console
 
 ## Convert a Jekyll lesson

diff --git a/content/executing-code.md b/content/executing-code.md
@@ -8,7 +8,7 @@ kernelspec:
 ---
 
 
-# Try executing code cells in markdown
+# Executing code cells in MyST markdown
 
 This is a `.md` file that has a special header and a `{code-cell}`
 directive, that lets it

diff --git a/content/exercise-list.md b/content/exercise-list.md
@@ -7,32 +7,52 @@ instructors and helpers, and more.
 
 ## Usage
 
-ReST:
-
-```
-.. exerciselist::
-```
-
 MyST:
 
 ````
 ```{exerciselist}```
 ````
 
+ReST:
+
+```
+.. 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
 <directives>` which match any `include`, and do not match any
 `exclude` are included).  Specify the options this way (ReST):
 
+MyST:
+
+````md
+```{exerciselist}
+:include: exercise solution instructor-note
+:exclude: exclude-this
 ```
+
+:::{exercise} Exercise title
+:class: exclude-this
+
+Exercise content
+:::
+````
+
+
+ReST:
+
+```rst
 .. exerciselist::
    :include: exercise solution instructor-note
    :exclude: exclude-this
 
-.. exercise::
+.. exercise:: Exercise title
    :class: exclude-this
+
+   Exercise content
 ```
 
 This feature is new as of early 2022, there may be possible problems
@@ -74,8 +94,9 @@ source for hint on fixing).
   (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
+- Consider giving your exercises permanent identifiers.  They are
+  intentionally not
+  auto-numbered yet (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`:
 
@@ -103,10 +124,13 @@ source for hint on fixing).
 
 ## 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.
+**This section contains the exercise list of sphinx-lesson.  Since
+sphinx-lesson has many examples of exercises, the list below is
+confusing and doesn't make a lot of sense.  You can see a better
+example at [git-intro's exercise
+list](https://coderefinery.github.io/git-intro/exercises/).**
+
+**Example begins:**
 
 :::{exerciselist}
 :::
diff --git a/content/getting-started.md b/content/getting-started.md
@@ -11,7 +11,8 @@ the lesson develops - you might want to check back for them, later.
 
 ## Convert an existing jekyll lesson
 
-See {doc}`convert-old-lessons`.
+See {doc}`convert-old-lessons`.  This hasn't been used in years so may
+be out of date.
 
 ## From scratch
 

diff --git a/content/gh-action.md b/content/gh-action.md
@@ -1,6 +1,6 @@
 # Deployment with Github Actions
 
-In this repository, there is a `.github/workflows/sphinx.yml` file
+In sphinx-lesson-template (and this lesson...), there is a `.github/workflows/sphinx.yml` file
 that contains a Github Action that:
 
 - Installs dependencies
@@ -9,11 +9,20 @@ that contains a Github Action that:
 
 - Deploys it
 
-  - If branch = `master` (to be renamed to `main`), deploy to github pages normally
+  - If branch = `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.
+
+## Usage
+
+It is recommended to copy from
+[sphinx-lesson-template](https://github.com/coderefinery/sphinx-lesson-template/),
+since that is the primary copy that is updated with all of the latest developments.
+
+Direct link:
+<https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml>
diff --git a/content/index.md b/content/index.md
@@ -9,6 +9,10 @@ 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.
 
+The broad idea is that making teaching materials should be quite
+similar to good software documentation.  Sphinx-lesson adds a model
+and a few nice extras to bring them closer together.
+
 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
@@ -25,16 +29,18 @@ Features:
 - 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
+- Markdown and ReStructured equally supported as input formats (yes, including all
+  directives).
 - 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/))
+  CommonMark with directives (mainly of use for old CodeRefinery lessons)
+- Also renders with sphinx-book-theme (theme of jupyterbook)
+  ([preview](https://coderefinery.github.io/sphinx-lesson/branch/sphinx-book-theme/))
+  and other Sphinx themes.
 
-This is in an alpha state: we use it for lessons, but there is still
-refinement work to go.
+This is in heavy internal use, and about ready for other users who are
+interested.
 
 :::{prereq}
 - If you know Sphinx, it helps some.  If not, it's easy to copy

diff --git a/content/indexing.md b/content/indexing.md
@@ -41,24 +41,11 @@ 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
-```
+### Index a block with a directive
 
 MyST:
 
-````
+````md
 ```{index} commit; amend
 ```
 
@@ -69,14 +56,24 @@ pair: commit; amend
 ```
 ````
 
-Or index a single term with the role:
+ReST:
 
 ```
-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 <pair: commit; amend>`.
+.. index:: commit; amend
 ```
 
+Or ReST, multiple:
+
+```
+.. index::
+   commit
+   commit; message
+   pair: commit; amend
+```
+
+
+### Index a single word with the role
+
 ```{index} pair: index; MyST
 ```
 
@@ -90,7 +87,16 @@ Pair entry: {index}`loop variables <pair: commit; amend>`
 ```{index} index; single index; pair index; see index; seealso
 ```
 
-There are different styles:
+ReST:
+
+```
+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 <pair: commit; amend>`.
+```
+
+
+### Styles of indexes
 
 - `TERM`, same as below
 - `single: TERM` (the default): create just a single entry

diff --git a/content/installation.md b/content/installation.md
@@ -32,19 +32,18 @@ preview of it [as a branch on github-pages](https://coderefinery.github.io/sphin
 
 ## 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.
+Adding `sphinx_lesson` as an extension adds these sub-extensions, and
+you could selectively enable only the parts you want:
+
+- `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/)