Test tutorials

.github/workflows/ci.yml

@@ -64,6 +64,9 @@ jobs:
           version: "0.5.7"
           python-version: "3.12"
 
+      - name: Install pandoc
+        uses: pandoc/actions/setup@v1
+
       - name: Install dependencies
         run: uv sync
 

.github/workflows/docs.yml

@@ -26,6 +26,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install pandoc
+        uses: pandoc/actions/setup@v1
+
       - name: Install uv
         uses: astral-sh/setup-uv@v4
         with:

.github/workflows/publish-on-pypi.yml

@@ -7,7 +7,50 @@ on:
       - v[0-9]+.[0-9]+.[0-9]+*
 
 jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    if: github.repository == 'stfc/janus-core' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    concurrency:
+      group: "pages"
+      cancel-in-progress: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pandoc
+        uses: pandoc/actions/setup@v1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.5.7"
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build docs with tutorials
+        run: cd docs && uv run make all
+
+      - name: Upload
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: './docs/build/html/.'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
   publish:
+    needs: build-docs
     runs-on: ubuntu-latest
     if: github.repository == 'stfc/janus-core' && startsWith(github.ref, 'refs/tags/v')
     environment:

docs/Makefile

@@ -26,16 +26,20 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 customdefault:
 	$(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
-all: html
+all: tutorials
 
 clean:
 	rm -rf $(BUILDDIR)
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -D nbsphinx_execute=never
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+tutorials:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 view:
 	xdg-open $(BUILDDIR)/html/index.html

docs/source/conf.py

@@ -32,6 +32,7 @@
     "sphinxcontrib.contentui",
     "sphinx_copybutton",
     "sphinx_autodoc_typehints",
+    "nbsphinx",
 ]
 
 always_use_bars_union = True

docs/source/developer_guide/get_started.rst

@@ -109,7 +109,10 @@ The full set of `ruff rules <https://docs.astral.sh/ruff/rules/>`_ are specified
 Building the documentation
 ++++++++++++++++++++++++++
 
-Packages in the ``docs`` dependency group install `Sphinx <https://www.sphinx-doc.org>`_ and other packages required to build ``janus-core``'s documentation.
+Packages in the ``docs`` dependency group install `Sphinx <https://www.sphinx-doc.org>`_
+and other Python packages required to build ``janus-core``'s documentation.
+
+It is also necessary to `install pandoc <https://pandoc.org/installing.html>`_ on your system.
 
 Individual individual documentation pages can be edited directly::
 
@@ -143,6 +146,19 @@ To document a new module, a new block must be added. For example, for the ``janu
         make clean; make html
 
 
+Notebook tutorials
+++++++++++++++++++
+
+Jupyter notebooks in ``docs/source/tutorials`` are automatically run by ``Sphinx`` using the
+`nbsphinx <https://nbsphinx.readthedocs.io/en/0.2.15/index.html>`_ extension, creating the :doc:`Tutorials </tutorials/index>`.
+
+
+These are tested before ``janus-core`` is published to PyPI, but can be tested locally by running::
+
+        cd docs
+        make clean; make tutorials
+
+
 Continuous integration
 ++++++++++++++++++++++
 

docs/source/index.rst

@@ -16,6 +16,7 @@ Welcome to janus-core's documentation!
 
    getting_started/getting_started
    user_guide/index
+   tutorials/index
    developer_guide/index
    API documentation <apidoc/janus_core>