docs: task-first Jupyter Book site (OLED, agents, CI)

.github/workflows/cifkit-docs.yml

@@ -0,0 +1,96 @@
+# Build the cifkit Jupyter Book and publish it to GitHub Pages.
+# Pages source is the gh-pages branch (Settings → Pages → Deploy from branch).
+# This workflow builds HTML then pushes it to gh-pages (same path as the
+# historical Sphinx deploy). Published at https://bobleesj.github.io/cifkit/
+#
+# Tutorial pages are plain MyST with pasted outputs; the runner installs the
+# package for autodoc only — nothing executes notebooks at build time.
+name: cifkit docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/cifkit/**"
+      - "pyproject.toml"
+      - "llms.txt"
+      - "CITATION.cff"
+      - "CHANGELOG.rst"
+      - "scripts/docs_e2e_check.py"
+      - ".github/workflows/cifkit-docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "src/cifkit/**"
+      - "pyproject.toml"
+      - "llms.txt"
+      - "CITATION.cff"
+      - "scripts/docs_e2e_check.py"
+      - ".github/workflows/cifkit-docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: cifkit-docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.repository == 'bobleesj/cifkit'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install -e .
+
+      - name: Build Jupyter Book
+        run: jupyter-book build docs
+
+      - name: End-to-end HTML checks
+        run: python scripts/docs_e2e_check.py
+
+      - name: Upload HTML artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cifkit-docs-html
+          path: docs/_build/html
+          retention-days: 7
+
+  deploy:
+    # Only publish from main after a green build (not on PRs).
+    if: >-
+      github.repository == 'bobleesj/cifkit'
+      && github.event_name != 'pull_request'
+      && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: cifkit-docs-html
+          path: docs/_build/html
+
+      - name: Re-run e2e on downloaded artifact
+        run: python scripts/docs_e2e_check.py
+
+      - name: Publish to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          force_orphan: true
+          user_name: github-actions[bot]
+          user_email: github-actions[bot]@users.noreply.github.com

.github/workflows/matrix-and-codecov-on-merge-to-main.yml → .github/workflows/matrix-on-merge-to-main.yml

@@ -11,9 +11,10 @@ on:
   workflow_dispatch:
 
 jobs:
-  matrix-coverage:
+  matrix-tests:
     uses: scikit-package/release-scripts/.github/workflows/_matrix-no-codecov-on-merge-to-main.yml@v0
     with:
       project: cifkit
       c_extension: false
-      headless: false
+      # Start Xvfb so VTK/pyvista polyhedron tests do not segfault
+      headless: true

.github/workflows/tests-on-pr.yml

@@ -10,4 +10,5 @@ jobs:
     with:
       project: cifkit
       c_extension: false
-      headless: false
+      # Start Xvfb so VTK/pyvista polyhedron tests do not segfault
+      headless: true

.gitignore

@@ -66,7 +66,8 @@ coverage.xml
 # Sphinx documentation
 docs/build/
 docs/_build/
-tests/data
+# Allow committed open test fixtures under tests/data/; ignore local dumps only
+tests/data/local/
 AXUGAE.cif
 FIXVUH.cif
 NUMSIB.cif

CITATION.cff

@@ -0,0 +1,108 @@
+cff-version: 1.2.0
+message: >
+  If cifkit, SAF/CAF feature generation, or the OLED (Oliynyk elemental
+  data) table was useful, consider citing the relevant work below.
+type: software
+title: cifkit
+abstract: >
+  Coordination geometry and atomic-site features from Crystallographic
+  Information Files (CIF), plus OLED (Oliynyk elemental data) for
+  composition featurization.
+authors:
+  - family-names: Lee
+    given-names: Sangjoon
+    orcid: "https://orcid.org/0000-0002-2367-3932"
+  - family-names: Oliynyk
+    given-names: Anton O.
+    orcid: "https://orcid.org/0000-0003-0732-7340"
+repository-code: "https://github.com/bobleesj/cifkit"
+url: "https://bobleesj.github.io/cifkit/"
+license: BSD-3-Clause
+identifiers:
+  - type: doi
+    value: 10.21105/joss.07205
+    description: cifkit JOSS paper
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Lee
+      given-names: Sangjoon
+    - family-names: Oliynyk
+      given-names: Anton O.
+  title: "cifkit: A Python package for coordination geometry and atomic site analysis"
+  journal: Journal of Open Source Software
+  year: 2024
+  volume: "9"
+  issue: "103"
+  start: 7205
+  doi: 10.21105/joss.07205
+references:
+  - type: article
+    authors:
+      - family-names: Lee
+        given-names: Sangjoon
+      - family-names: Chen
+        given-names: C.
+      - family-names: Garcia
+        given-names: G.
+      - family-names: Oliynyk
+        given-names: Anton
+    title: >-
+      Machine learning descriptors in materials chemistry used in multiple
+      experimentally validated studies: Oliynyk elemental property dataset
+    journal: Data in Brief
+    year: 2024
+    volume: "53"
+    doi: 10.1016/j.dib.2024.110178
+    notes: OLED (Oliynyk elemental data) - cite when using the elemental property table
+  - type: article
+    authors:
+      - family-names: Jaffal
+        given-names: Emil I.
+      - family-names: Lee
+        given-names: Sangjoon
+      - family-names: Shiryaev
+        given-names: Danila
+      - family-names: Vtorov
+        given-names: Alex
+      - family-names: Barua
+        given-names: Nikhil Kumar
+      - family-names: Kleinke
+        given-names: Holger
+      - family-names: Oliynyk
+        given-names: Anton O.
+    title: >-
+      Composition and structure analyzer/featurizer for explainable
+      machine-learning models to predict solid state structures
+    journal: Digital Discovery
+    year: 2025
+    volume: "4"
+    start: 548
+    end: 560
+    doi: 10.1039/d4dd00332b
+    notes: >-
+      SAF (structure) and CAF (composition) feature generation for ML;
+      cifkit is the geometry engine for SAF
+  - type: article
+    authors:
+      - family-names: Lee
+        given-names: Sangjoon
+      - family-names: Myers
+        given-names: C.
+      - family-names: Yang
+        given-names: A.
+      - family-names: Zhang
+        given-names: T.
+      - family-names: Xiao
+        given-names: Y.
+      - family-names: Billinge
+        given-names: S. J. L.
+    title: >-
+      scikit-package: software packaging standards and roadmap for
+      sharing reproducible scientific software
+    journal: Digital Discovery
+    year: 2026
+    doi: 10.1039/d6dd00121a
+    notes: >-
+      Packaging standards and roadmap; cifkit is built and maintained
+      with scikit-package