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.

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 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).

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.