It is built the normal Sphinx way:

However, there are different ways to set up a Sphinx project. Our

sample project puts the results in `_build/`.

- First PyPI release

myst_enable_extensions = [

"colon_fence",

]

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

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:

[CodeRefinery's git-intro lesson](https://coderefinery.github.io/git-intro/) explains more.

The material is in the `content/` directory. Depending on the

lesson, in may be in ReStructured Text, MyST Markdown, or Jupyter

notebooks.

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

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

:::{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):

You can build it using either of these commands:

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:

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.

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