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:

README.md

@@ -12,6 +12,15 @@
 
 Tools for machine learnt interatomic potentials
 
+## Contents
+- [Getting started](#getting-started)
+- [Features](#features)
+- [Python interface](#python-interface)
+- [Command line interface](#command-line-interface)
+- [Development](#development)
+- [License](#license)
+- [Funding](#funding)
+
 ## Getting started
 
 ### Dependencies
@@ -104,6 +113,87 @@ Current and planned features include:
 - [ ] Rare events simulations
   - PLUMED
 
+
+## Python interface
+
+Calculations can also be run through the Python interface. For example, running:
+
+```python
+from janus_core.calculations.single_point import SinglePoint
+
+single_point = SinglePoint(
+    struct_path="tests/data/NaCl.cif",
+    arch="mace_mp",
+    model_path="tests/models/mace_mp_small.model",
+)
+
+results = single_point.run()
+print(results)
+```
+
+will read the NaCl structure file and attach the MACE-MP (medium) calculator, before calculating and printing the energy, forces, and stress.
+
+Jupyter Notebook tutorials illustrating the use of currently available calculations can be found in the [tutorials](https://github.com/stfc/janus-core/tree/main/docs/source/tutorials) documentation directory. This currently includes examples for:
+
+- [Single Point](docs/source/tutorials/single_point.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/single_point.ipynb)
+- [Geometry Optimization](docs/source/tutorials/geom_opt.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/geom_opt.ipynb)
+- [Molecular Dynamics](docs/source/tutorials/md.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/md.ipynb)
+- [Equation of State](docs/source/tutorials/eos.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/eos.ipynb)
+- [Phonons](docs/source/tutorials/phonons.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/phonons.ipynb)
+
+
+### Calculation outputs
+
+By default, calculations performed will modify the underlying [ase.Atoms](https://wiki.fysik.dtu.dk/ase/ase/atoms.html) object
+to store information in the `Atoms.info` and `Atoms.arrays` dictionaries about the MLIP used.
+
+Additional dictionary keys include `arch`, corresponding to the MLIP architecture used,
+and `model_path`, corresponding to the model path, name or label.
+
+Results from the MLIP calculator, which are typically stored in `Atoms.calc.results`, will also, by default,
+be copied to these dictionaries, prefixed by the MLIP `arch`.
+
+For example:
+
+```python
+from janus_core.calculations.single_point import SinglePoint
+
+single_point = SinglePoint(
+    struct_path="tests/data/NaCl.cif",
+    arch="mace_mp",
+    model_path="tests/models/mace_mp_small.model",
+)
+
+single_point.run()
+print(single_point.struct.info)
+```
+
+will return
+
+```python
+{
+  'spacegroup': Spacegroup(1, setting=1),
+  'unit_cell': 'conventional',
+  'occupancy': {'0': {'Na': 1.0}, '1': {'Cl': 1.0}, '2': {'Na': 1.0}, '3': {'Cl': 1.0}, '4': {'Na': 1.0}, '5': {'Cl': 1.0}, '6': {'Na': 1.0}, '7': {'Cl': 1.0}},
+  'model_path': 'tests/models/mace_mp_small.model',
+  'arch': 'mace_mp',
+  'mace_mp_energy': -27.035127799332745,
+  'mace_mp_stress': array([-4.78327600e-03, -4.78327600e-03, -4.78327600e-03,  1.08000967e-19, -2.74004242e-19, -2.04504710e-19]),
+  'system_name': 'NaCl',
+}
+```
+
+> [!NOTE]
+> If running calculations with multiple MLIPs, `arch` and `mlip_model` will be overwritten with the most recent MLIP information.
+> Results labelled by the architecture (e.g. `mace_mp_energy`) will be saved between MLIPs,
+> unless the same `arch` is chosen, in which case these values will also be overwritten.
+
+This is also the case the calculations performed using the CLI, with the same information written to extxyz output files.
+
+> [!TIP]
+> For complete provenance tracking, calculations and training can be run using the [aiida-mlip](https://github.com/stfc/aiida-mlip/) AiiDA plugin.
+
+
 ## Command line interface
 
 All supported MLIP calculations are accessible through subcommands of the `janus` command line tool, which is installed with the package:
@@ -200,86 +290,6 @@ This will run a singlepoint energy calculation on `KCl.cif` using the [MACE-MP](
 Example configurations for all commands can be found in [janus-tutorials](https://github.com/stfc/janus-tutorials/tree/main/configs)
 
 
-## Python interface
-
-Calculations can also be run through the Python interface. For example, running:
-
-```python
-from janus_core.calculations.single_point import SinglePoint
-
-single_point = SinglePoint(
-    struct_path="tests/data/NaCl.cif",
-    arch="mace_mp",
-    model_path="tests/models/mace_mp_small.model",
-)
-
-results = single_point.run()
-print(results)
-```
-
-will read the NaCl structure file and attach the MACE-MP (medium) calculator, before calculating and printing the energy, forces, and stress.
-
-Jupyter Notebook tutorials illustrating the use of currently available calculations can be found in the [janus-tutorials](https://github.com/stfc/janus-tutorials) repository. This currently includes examples for:
-
-- [Single Point](https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/single_point.ipynb)
-- [Geometry Optimization](https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/geom_opt.ipynb)
-- [Molecular Dynamics](https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/md.ipynb)
-- [Equation of State](https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/eos.ipynb)
-- [Phonons](https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/phonons.ipynb)
-
-
-## Calculation outputs
-
-By default, calculations performed will modify the underlying [ase.Atoms](https://wiki.fysik.dtu.dk/ase/ase/atoms.html) object
-to store information in the `Atoms.info` and `Atoms.arrays` dictionaries about the MLIP used.
-
-Additional dictionary keys include `arch`, corresponding to the MLIP architecture used,
-and `model_path`, corresponding to the model path, name or label.
-
-Results from the MLIP calculator, which are typically stored in `Atoms.calc.results`, will also, by default,
-be copied to these dictionaries, prefixed by the MLIP `arch`.
-
-For example:
-
-```python
-from janus_core.calculations.single_point import SinglePoint
-
-single_point = SinglePoint(
-    struct_path="tests/data/NaCl.cif",
-    arch="mace_mp",
-    model_path="tests/models/mace_mp_small.model",
-)
-
-single_point.run()
-print(single_point.struct.info)
-```
-
-will return
-
-```python
-{
-  'spacegroup': Spacegroup(1, setting=1),
-  'unit_cell': 'conventional',
-  'occupancy': {'0': {'Na': 1.0}, '1': {'Cl': 1.0}, '2': {'Na': 1.0}, '3': {'Cl': 1.0}, '4': {'Na': 1.0}, '5': {'Cl': 1.0}, '6': {'Na': 1.0}, '7': {'Cl': 1.0}},
-  'model_path': 'tests/models/mace_mp_small.model',
-  'arch': 'mace_mp',
-  'mace_mp_energy': -27.035127799332745,
-  'mace_mp_stress': array([-4.78327600e-03, -4.78327600e-03, -4.78327600e-03,  1.08000967e-19, -2.74004242e-19, -2.04504710e-19]),
-  'system_name': 'NaCl',
-}
-```
-
-> [!NOTE]
-> If running calculations with multiple MLIPs, `arch` and `mlip_model` will be overwritten with the most recent MLIP information.
-> Results labelled by the architecture (e.g. `mace_mp_energy`) will be saved between MLIPs,
-> unless the same `arch` is chosen, in which case these values will also be overwritten.
-
-This is also the case the calculations performed using the CLI, with the same information written to extxyz output files.
-
-> [!TIP]
-> For complete provenance tracking, calculations and training can be run using the [aiida-mlip](https://github.com/stfc/aiida-mlip/) AiiDA plugin.
-
-
 ## Development
 
 We recommend installing uv for dependency management when developing for `janus-core`:

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>