Getting started

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 Converting an old lesson.

From scratch

See the next page, Installation, for raw Python packages to install and how to configure a arbitrary Sphinx project.

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 non-human gh-pages push won’t enable Github Pages. So, you have to 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):

git checkout -b gh-pages origin/gh-pages
git commit -m 'empty commit to trigger gh-pages' --allow-empty
git push

Demo lessons

This guide can’t currently stand alone. It is probably good to look at and copy from existing lessons for some things: