sphinx-lesson: structured lessons with Sphinx
See also
See a real demo lesson at https://coderefinery.github.io/github-without-command-line/.
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.
As the name says, it is based on the Sphinx documentation generator. It is also inspired by and based on jupyter-book, but both is jupyter-book and isn’t. It is because jupyter-book is based on Sphinx and modular, we reuse all of those same Sphinx extensions which jupyter-book has made. It isn’t jupyter-book because we configure Sphinx directly, instead of wrapping it through jupyter-book configuration and building. Thus, we get full control and high compatibility.
Features:
Separate content and presentation: easy to adjust theme or control the parts independently.
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
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)
This is in an alpha state: we use it for lessons, but there is still refinement work to go.
Prerequisites
If you know Sphinx, it helps some. If not, it’s easy to copy
Markdown or ReStructured text
Hosting is usually by github-pages
Getting started
Basic syntax
Examples
Advanced features
Extras