Merge pull request coderefinery#103 from coderefinery/rkdarst/rst-to-…

…myst

Convert ReST to Myst

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/`.

content/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.8.0
+
+- First PyPI release

content/cheatsheet.rst → content/cheatsheet.md

@@ -1,4 +1,3 @@
-Cheatsheet
-==========
+# Cheatsheet
 
 This is the cheatsheet.

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']
 

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 <md-and-rst>`.  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 <sphinx:rst-primer>`
+- [MyST reference](https://myst-parser.readthedocs.io/en/latest/using/syntax.html)
+- {doc}`sphinx-lesson directives for markup <directives>`
+
+*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.