https://github.com/coderefinery/sphinx-lesson
Sphinx extension for creating CodeRefinery lessons
https://github.com/coderefinery/sphinx-lesson
Last synced: 5 months ago
JSON representation
Sphinx extension for creating CodeRefinery lessons
- Host: GitHub
- URL: https://github.com/coderefinery/sphinx-lesson
- Owner: coderefinery
- License: mit
- Created: 2020-05-17T18:01:22.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2026-01-21T20:04:42.000Z (5 months ago)
- Last Synced: 2026-01-22T08:57:51.159Z (5 months ago)
- Language: Python
- Homepage: https://coderefinery.github.io/sphinx-lesson/
- Size: 8.2 MB
- Stars: 16
- Watchers: 14
- Forks: 21
- Open Issues: 14
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
Sphinx test lesson
==================
This is a Sphinx extension for software-carpentry style
lessons. It is designed as a replacement for the Jekyll-based software
templates.
* `View the documentation (and example) on github pages
`__.
* `Template repository, to copy from
`__.
Features
--------
- Sphinx, including power from all of its extensions.
- ReST
- Markdown via the `myst_parser` parser, so has access to all Sphinx
directives natively
- Jupyter as a source format, including executing the notebook (via
``myst_nb``).
- Automatically building via Github Actions and automatic deployment
to Github Pages. Included workflow file builds all branches, so you
can also preview pull requests.
- Directives for exercises/prereq/etc, works in both ReST and md.
- The Sphinx part can be separated into a separately installable
and versionable Python package, so we don't need git sub-modules.
- Execute code cells in markdown (via ``myst_nb``).
- Consists of sub-extensions for substitutions. Adding
``sphinx_lesson`` as an extension will bring in these:
- ``sphinx_lesson.directives`` (the core directives)
- ``sphinx_lesson.md_transforms`` (reprocess some other markdown
format into myst_nb format)
- ``myst_nb`` (not developed by us)
Host Site Locally for Development
---------------------------------
1. Create a virtual python environment::
python -m venv venv
2. Activate the virtual environment::
source activate venv/bin/activate
3. Install python packages::
pip install -r requirements.txt
4. Build local files (this can also be used for deployment)::
make html
# Output in _build/html/
make clean html # clean + full rebuild
5. Or, start a live-compiled service for your compiled site for local development::
make livehtml
Then view created site in your browser at `http://localhost:8000 `__ (follow the link in your console).
Status
------
In beta use by CodeRefinery and active development. External users
would be fine (but let us know so we know to keep things stable).