docs: publish Zensical documentation site

.github/workflows/docs.yaml

@@ -0,0 +1,77 @@
+name: documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - '.github/workflows/docs.yaml'
+              - 'docs/**'
+              - 'src/**'
+              - 'pyproject.toml'
+              - 'uv.lock'
+              - 'zensical.toml'
+
+  build:
+    needs: changes
+    if: ${{ needs.changes.outputs.docs == 'true' || github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          python-version: "3.13"
+      - name: Build documentation
+        run: uv run --extra docs --no-dev zensical build --clean --strict
+      - name: Configure Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

.gitignore

@@ -10,6 +10,7 @@ dist/
 .pytest_cache/
 .coverage
 htmlcov/
+site/
 .ipynb_checkpoints/
 
 .DS_Store

README.md

@@ -1,81 +1,19 @@
 <div align="center">
 
-# <img src="./logo.svg" alt="SpinForge" width="450">
+# <img src="./docs/assets/logo.svg" alt="SpinForge" width="450">
 
 </div>
 
 SpinForge is a group-theoretic generator for spin-symmetry-adapted (SSA) and
 oriented magnetic crystal structures based on spin space groups.
 
-## Installation
+[Documentation](https://spglib.github.io/spinforge/) ·
+[PyPI](https://pypi.org/project/spinforge/) ·
+[Issue tracker](https://github.com/spglib/spinforge/issues)
 
-SpinForge supports Python 3.11 and later.
-
-```shell
-python -m pip install spinforge
-```
-
-For a source checkout and contributor setup, see
-[CONTRIBUTING.md](./CONTRIBUTING.md).
-
-## Quickstart: oriented magnetic structures
-
-Given a primitive crystal structure in `MnTe.cif`, this example enumerates
-collinear SSA candidates with propagation-vector index one and generates every
-maximal oriented descendant:
-
-```python
-from moyopy import Cell
-from pymatgen.core import Structure
-from spinspg.spin import SpinOnlyGroupType
-
-from spinforge.configuration import SSAGenerator
-
-structure = Structure.from_file("MnTe.cif")
-prim_cell = Cell(
-    basis=structure.lattice.matrix.tolist(),
-    positions=structure.frac_coords.tolist(),
-    numbers=list(structure.atomic_numbers),
-)
-magnetic_site_indices = [
-    index for index, atomic_number in enumerate(prim_cell.numbers) if atomic_number == 25
-]
-
-generator = SSAGenerator(
-    prim_cell=prim_cell,
-    magnetic_site_indices=magnetic_site_indices,
-)
-
-for spin_only_group, spin_space_group, adapted_structure in generator.enumerate(
-    spin_only_group_type=SpinOnlyGroupType.COLLINEAR,
-    k_index=1,
-    max_depth=0,
-):
-    oriented_structures = generator.generate_oriented(
-        adapted_structure,
-        spin_only_group=spin_only_group,
-        nontrivial_spin_space_group=spin_space_group,
-    )
-    for magnetic_structure, magnetic_space_subgroup in oriented_structures:
-        print(magnetic_structure.formula, magnetic_space_subgroup.msg_type)
-```
-
-`SSAGenerator` requires a primitive input cell. The family-subgroup,
-spin-space-group, and oriented spin-frame equivalence controls are separate.
-See the [enumeration and equivalence guide](./docs/equivalence.md) for the
-precise criteria and the options for larger searches.
-
-## Examples
-
-The paper examples are provided as notebooks in [`examples/paper`](./examples/paper):
-
-- [collinear MnTe](./examples/paper/collinear_MnTe)
-- [coplanar Mn3Sn](./examples/paper/coplanar_Mn3Sn)
-- [noncoplanar CoTa3S6](./examples/paper/noncoplanar_CoTa3S6)
-
-These examples are published as-is. The paper figures, MAGNDATA-derived
-datasets, and the raw 283-material SDFT workflow are not part of this
-repository.
+Installation, tutorials, examples, citation guidance, and API references are
+maintained in the [documentation](https://spglib.github.io/spinforge/). For a
+source checkout and contributor setup, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Release flow
 
@@ -129,30 +67,6 @@ Please use
 bugs and in-scope feature requests. Security reports follow
 [SECURITY.md](./SECURITY.md).
 
-## Citation
-
-If SpinForge contributes to published work, cite the software metadata in
-[`CITATION.cff`](./CITATION.cff) and the associated oriented-spin-space-group
-paper:
-
-> T. Nomoto, K. Shinohara, H. Watanabe, and R. Arita,
-> “Systematic magnetic structure generation based on oriented spin space
-> groups: Formulation, applications, and high-throughput first-principles
-> calculations,” *Physical Review X* (accepted 2026).
-> [doi:10.1103/8n3w-h2t1](https://doi.org/10.1103/8n3w-h2t1)
-
-```bibtex
-@article{SpinForgePRX2026,
-  author = {Nomoto, Takuya and Shinohara, Kohei and Watanabe, Hikaru and Arita, Ryotaro},
-  title = {Systematic Magnetic Structure Generation Based on Oriented Spin Space Groups:
-           Formulation, Applications, and High-Throughput First-Principles Calculations},
-  journal = {Physical Review X},
-  year = {2026},
-  doi = {10.1103/8n3w-h2t1},
-  note = {Accepted}
-}
-```
-
 ## Data attribution and license
 
 Third-party and literature-derived fixture notices are collected in

docs/THIRD_PARTY_DATA.md

@@ -36,8 +36,9 @@ Please cite:
 ## MnTe structural model
 
 `src/spinforge/testing/assets/MnTe.cif` and
-`examples/paper/collinear_MnTe/MnTe.cif` are identical, locally serialized
-pymatgen CIFs for the NiAs-type MnTe structure. The lattice constants
+`examples/paper/collinear_MnTe/MnTe.cif` are identical to the documentation
+copy at `docs/paper/MnTe.cif`. They are locally serialized pymatgen CIFs for
+the NiAs-type MnTe structure. The lattice constants
 `a = b = 4.17349018 Å` and `c = 6.75345133 Å` follow the supplemental
 material to:
 
@@ -74,3 +75,24 @@ The SpinForge fixture is not a byte-for-byte COD or MAGNDATA record.
 within the SpinForge project. Repository history records no external database
 file as its source, so no third-party dataset license is asserted for this
 file.
+
+## Article example figures
+
+The following PNG schematics under `docs/assets/paper/` illustrate examples
+from the associated article:
+
+- `fig_example_collinear.png`
+- `fig_example_coplanar.png`
+- `fig_example_noncoplanar.png`
+
+The figures were created for:
+
+> T. Nomoto, K. Shinohara, H. Watanabe, and R. Arita,
+> “Systematic magnetic structure generation based on oriented spin space
+> groups: Formulation, applications, and high-throughput first-principles
+> calculations,” *Physical Review X* (accepted 2026).
+> [doi:10.1103/8n3w-h2t1](https://doi.org/10.1103/8n3w-h2t1)
+
+They are included with permission from their copyright holder, granted on
+September 6, 2026. This notice records that permission without asserting a
+Creative Commons license before the article's Version of Record is published.

docs/api/configuration.md

@@ -0,0 +1,5 @@
+# Configuration
+
+High-level structure generation and supercell objects.
+
+::: spinforge.configuration

docs/api/irreps.md

@@ -0,0 +1,6 @@
+# Irreducible representations
+
+Real irreducible-representation and intertwiner utilities used by the
+spin-space-group enumerators.
+
+::: spinforge.irreps

docs/api/magnetic-space-group.md

@@ -0,0 +1,5 @@
+# Magnetic space groups
+
+Oriented descendants and magnetic-space-subgroup objects.
+
+::: spinforge.msg

docs/api/mcif.md

@@ -0,0 +1,6 @@
+# MCIF
+
+Write a pymatgen magnetic structure as a symmetrized magnetic CIF in the
+BNS/MAGNDATA convention.
+
+::: spinforge.mcif

docs/api/space-group.md

@@ -0,0 +1,6 @@
+# Space groups
+
+Family and normal space-subgroup enumeration, parent-normalizer actions, and
+translation sublattices.
+
+::: spinforge.space_group

docs/api/spin-space-group.md

@@ -0,0 +1,5 @@
+# Spin space groups
+
+Nontrivial spin space groups, symmetry operations, and subgroup enumeration.
+
+::: spinforge.ssg

docs/api/spincif.md

@@ -0,0 +1,5 @@
+# spinCIF
+
+Read and write SpinForge's supported subset of the draft spinCIF format.
+
+::: spinforge.scif