Automatic docs

.github/workflows/docs-build-test-deploy.yml

@@ -0,0 +1,84 @@
+name: Test documentation build
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+
+env:
+  CACHE_NUMBER: 0  # increase to reset cache manually
+
+jobs:
+  build:
+
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
+
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            label: linux-64
+            prefix: /usr/share/miniconda3/envs/my-env
+
+    name: ${{ matrix.label }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Miniforge
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+            miniforge-version: latest
+            activate-environment: my-env
+
+      - name: Set cache date
+        run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ matrix.prefix }}
+          key: ${{ matrix.label }}-conda-${{ hashFiles('environment.yml') }}-${{ env.DATE }}-${{ env.CACHE_NUMBER }}
+        id: cache
+
+      - name: Update environment
+        run: conda env update -n my-env -f environment.yml
+        if: steps.cache.outputs.cache-hit != 'true'
+
+      - name: Install documentation requirements
+        shell: bash -l {0}
+        run: pip install -r docs/requirements.txt
+
+      - name: Build documentation src
+        shell: bash -l {0}
+        run: make build-src -C docs/
+
+      - name: Build HTML
+        shell: bash -l {0}
+        run: make html -C docs/
+
+      - name: Upload artifacts
+        if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html/
+
+  deploy:
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+
+    permissions:
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Deploy
+        uses: actions/deploy-pages@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/lint.yml

@@ -3,10 +3,14 @@ name: Lint with Ruff
 on:
   push:
     branches:
-      - main
+      - '*'
   pull_request:
+    branches:
+      - '*'
+
 jobs:
   lint:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

.github/workflows/python-package-conda-cache.yml

@@ -24,6 +24,10 @@ env:
 jobs:
   build:
 
+    # https://github.com/orgs/community/discussions/57827
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
+
+
     strategy:
       matrix:
         include:
@@ -34,7 +38,7 @@ jobs:
     name: ${{ matrix.label }}
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Build C
         run: make -C qstack/regression/lib/

.gitignore

@@ -9,6 +9,11 @@ __pycache__/
 # C extensions
 *.so
 
+# docs
+docs/source/qstack
+docs/source/index.rst
+docs/build/
+
 # Distribution / packaging
 .Python
 build/
@@ -73,6 +78,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
+docs/source/qstack
 
 # PyBuilder
 target/

README.md

@@ -6,28 +6,12 @@ Q-stack
 <p align="center"><img alt="qstack logo" align="center" src="./images/logo.png" width=66%></p>
 
 
-## Contents
-* [Contents](#Contents-)
-* [About](#about-)
-* [Install](#install-)
-* [Examples](#examples-)
-* [References](#references-)
-* [Acknowledgements](#acknowledgements-)
+## About
 
-## About [↑](#contents)
+Q-stack is a stack of codes for dedicated pre- and post-processing tasks for Quantum Machine Learning (QML).
+It is a work in progress. Stay tuned for updates!
 
-Q-stack is a stack of codes for dedicated pre- and post-processing tasks for Quantum Machine Learning (QML). It is a work in progress. Stay tuned for updates!
-
-For now, we link to the relevant packages that will be incorporated (among others):
-- [x] https://github.com/lcmd-epfl/azo-xcite-tools
-- [x] https://github.com/lcmd-epfl/SPAHM
-- [x] https://github.com/lcmd-epfl/SPAHM-RHO
-- [x] https://github.com/lcmd-epfl/RHO-Decomposition
-- [ ] https://github.com/lcmd-epfl/ml-density
-- [x] https://github.com/lcmd-epfl/OTPD-basis
-- [x] https://github.com/lcmd-epfl/b2r2-reaction-rep
-
-## Install [↑](#contents)
+## Install
 
 The installation of the library for python use can be done executing one of the following commands:
 
@@ -39,44 +23,85 @@ python -m pip install "qstack[all] @ git+https://github.com/lcmd-epfl/Q-stack.gi
 
 The last one is recommended if you do not know which features you wish to use, since they pull the dependencies required with all 'optional' parts of Q-stack.
 
+### Features:
+
+| feature | capability  |
+|---|---|
+| `[pyscf]` | quantum-chemical computations, wrappers, and conversion tools |
+| `[qml]` | stucture-based representations such as SLATM, SLATM_d, B2R2 (no quantum chemistry) |
+| `[spahm]` | SPAHM (ε-SPAHM, SPAHM(a,b)) representations |
+| `[cell2mol]` | interface with [cell2mol](https://github.com/lcmd-epfl/cell2mol) |
+| `[equio]`   | interface with [metatensor](https://github.com/metatensor/metatensor) |
+| `[regression]` | tools to run kernel ridge regression (no quantum chemistry) | 
+| `[wigner]` | tool to compute Wigner d-matrices for real spherical harmonics |
+
+
 If you want to be able to edit Q-stack's code after installing, you need to download it yourself, for instance with this series of commands
 
 ```bash
 git clone https://github.com/lcmd-epfl/Q-stack
 cd Q-stack
 
 #optionally, run the following line, if you want to be extra-careful about reproducibility, by installing a well-known version of all dependencies
-python -m pip install -r requirements.py3.11.txt   # (or "requirements.py3.9.txt" if you have an older version of python and that first file doesn't work)
+python -m pip install -r requirements.py3.13.txt   # (or "requirements.py3.{9,11}.txt" if you have an older version of python and that first file doesn't work)
 
 python -m pip install -e .[all]    # note: this translates as "install as '-e'ditable, install from this directory ('.'), with optional feature 'all'"
 ```
 
 For the optional step above, we also have an `environment.yml` file available, if you prefer working with conda environments.
 
 
-## Examples [↑](#contents)
-Q-stack comes with several example codes that illustrate some of its key capabilities. To run the examples, go to the example folder and run the following commands:
+## Examples
+Q-stack comes with several example codes that illustrate some of its key capabilities.
+Check out the `examples/` and `tests/` folders:
 
-- Field decomposition:
-```
-python example_deco.py
-```
-- Computation of Hirshfeld charges:
-```
-python example_hirsh.py
-```
-- Basis set optimization:
-```
-python example_opt.py
-```
-- Generation of the SPAHM representation:
-```
-python example_SPAHM.py
-```
-- An example for the structure-based reaction representations ($B^2R^2$ and $\mathrm{SLATM}_d$) will follow shortly
+* Field decomposition:
+  - [`examples/example_deco.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/examples/example_deco.py)
+  - [`tests/test_fitting.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_fitting.py)
+
+* Computation of Hirshfeld charges:
+  - [`examples/example_hirsh.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/examples/example_hirsh.py)
+
+* Basis set optimization:
+  - [`examples/example_opt.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/examples/example_opt.py)
+
+* Generation of the ε-SPAHM representation:
+  - [`examples/example_SPAHM.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/examples/example_SPAHM.py)
+  - [`tests/test_spahm.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_spahm.py)
+  - [`tests/test_spahm_grad.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_spahm_grad.py)
+
+* Generation of the SPAHM(a,b) representations:
+  - [`tests/test_spahm_a.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_spahm_a.py)
+  - [`tests/test_spahm_b.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_spahm_b.py)
+  - [`tests/test_spahm_b_selected.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_spahm_b_selected.py)
+
+* Reaction representations ($B^2R^2$ and $\mathrm{SLATM}_d$):
+  - [`tests/test_rxn-repr.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_rxn-repr.py)
+
+* Computation of DORI (density overlap regions indicator):
+  - [`tests/test_dori.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_dori.py)
+
+* Interface with [cell2mol](https://github.com/lcmd-epfl/cell2mol):
+  - [`tests/test_c2mio.py`](https://github.com/lcmd-epfl/Q-stack/tree/master/tests/test_c2mio.py)
+
+* Parsing ORCA binary output:
+  - [`examples/example_orcaio.py`](https://github.com/lcmd-epfl/tree/master/examples/example_orcaio.py)
+  - [`tests/test_orca.py`](https://github.com/lcmd-epfl/tree/master/tests/test_orca.py)
+
+
+## Sources
+
+Relevant packages incorporated (among others):
+* [https://github.com/lcmd-epfl/azo-xcite-tools](https://github.com/lcmd-epfl/azo-xcite-tools)
+* [https://github.com/lcmd-epfl/SPAHM](https://github.com/lcmd-epfl/SPAHM)
+* [https://github.com/lcmd-epfl/SPAHM-RHO](https://github.com/lcmd-epfl/SPAHM-RHO)
+* [https://github.com/lcmd-epfl/RHO-Decomposition](https://github.com/lcmd-epfl/RHO-Decomposition)
+* [https://github.com/lcmd-epfl/OTPD-basis](https://github.com/lcmd-epfl/OTPD-basis)
+* [https://github.com/lcmd-epfl/b2r2-reaction-rep](https://github.com/lcmd-epfl/b2r2-reaction-rep)
+* [https://github.com/lcmd-epfl/ml-density](https://github.com/lcmd-epfl/ml-density)
 
 
-## References [↑](#contents)
+## References
 
 * A. Fabrizio, A. Grisafi, B. Meyer, M. Ceriotti, and C. Corminboeuf,
   “Electron density learning of non-covalent systems”,
@@ -114,7 +139,7 @@ python example_SPAHM.py
   [![DOI](https://img.shields.io/badge/DOI-10.1088/2632--2153/ac8f1a-blue)](https://doi.org/10.1088/2632-2153/ac8f1a)
 
 
-## Acknowledgements [↑](#contents)
+## Acknowledgements
 The authors of Q-stack acknowledge the National Centre of Competence in Research (NCCR)
 "Materials' Revolution: Computational Design and Discovery of Novel Materials (MARVEL)" 
 of the Swiss National Science Foundation (SNSF, grant number 182892)

docs/Makefile

@@ -1,6 +1,3 @@
-# Minimal makefile for Sphinx documentation
-#
-
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
@@ -12,6 +9,16 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+docs:
+	make build-src
+	make html
+
+clean-src:
+	@rm -rfv source/qstack/ source/index.rst
+
+build-src:
+	@python generate_rst.py ../qstack/ -o source/ --project "Qstack" --package-root-name qstack
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/README.md

@@ -0,0 +1,15 @@
+# Instructions to create the documentation in html format
+
+Install Sphinx:
+
+```bash
+pip install -r requirements.txt
+```
+
+```bash
+make clean clean-src
+make docs
+```
+
+You can access the documenation on `Q-stack/docs/build/html/index.html`
+