Set up documentation

.github/workflows/Documentation.yml

@@ -0,0 +1,38 @@
+name: Documentation
+
+permissions:
+  contents: write
+  pages: write
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'main'
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        version:
+          - '1' # automatically expands to the latest stable 1.x release of Julia
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v5
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+        run: julia --project=docs/ docs/make.jl

.github/workflows/DocumentationPreviewCleanup.yml

@@ -0,0 +1,33 @@
+name: Documentation Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v5
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

.github/workflows/DocumentationPreviewComment.yml

@@ -0,0 +1,17 @@
+name: Documentation Preview Comment
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  pull-requests: write
+jobs:
+  pr_comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR comment
+        if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name && github.event.label.name == 'documentation'
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: 'After the build completes, the updated documentation will be available [here](https://quantumkithub.github.io/TensorKitSectors.jl/previews/PR${{ github.event.number }}/)'
+          comment-tag: 'preview-doc'

.gitignore

@@ -1,5 +1,6 @@
 *.jl.*.cov
 *.jl.cov
 *.jl.mem
-/Manifest.toml
-.DS_Store
+Manifest.toml
+.DS_Store
+build

README.md

@@ -2,9 +2,15 @@
 
 A Julia package for working with objects in fusion categories.
 
-| **Build Status** | **PkgEval** | **Coverage** | **Quality assurance** |
-|:----------------:|:------------:|:------------:|:---------------------:|
-| [![CI][ci-img]][ci-url] | [![PkgEval][pkgeval-img]][pkgeval-url] | [![Codecov][codecov-img]][codecov-url] | [![Aqua QA][aqua-img]][aqua-url] |
+| **Documentation** | **Build Status** | **PkgEval** | **Coverage** | **Quality assurance** |
+|:-----------------:|:----------------:|:-----------:|:------------:|:---------------------:|
+| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![CI][ci-img]][ci-url] | [![PkgEval][pkgeval-img]][pkgeval-url] | [![Codecov][codecov-img]][codecov-url] | [![Aqua QA][aqua-img]][aqua-url] |
+
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://QuantumKitHub.github.io/TensorKitSectors.jl/stable
+
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://QuantumKitHub.github.io/TensorKitSectors.jl/latest
 
 [ci-img]: https://github.com/QuantumKitHub/TensorKitSectors.jl/actions/workflows/CI.yml/badge.svg
 [ci-url]: https://github.com/QuantumKitHub/TensorKitSectors.jl/actions/workflows/CI.yml

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+TensorKitSectors = "13a9c161-d5da-41f0-bcbd-e1a08ae0647f"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,27 @@
+using TensorKitSectors
+using Documenter
+
+mathengine = MathJax3(
+    Dict(
+        :loader => Dict("load" => ["[tex]/physics"]),
+        :tex => Dict(
+            "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
+            "tags" => "ams",
+            "packages" => ["base", "ams", "autoload", "physics"]
+        )
+    )
+)
+makedocs(;
+    sitename = "TensorKitSectors.jl",
+    format = Documenter.HTML(;
+        prettyurls = true,
+        mathengine,
+    ),
+    pages = [
+        "Home" => "index.md",
+        "Library" => "lib.md",
+    ],
+    checkdocs = :exports,
+)
+
+deploydocs(; repo = "github.com/QuantumKitHub/TensorKitSectors.jl.git", push_preview = true)

docs/src/index.md

@@ -0,0 +1,12 @@
+# TensorKitSectors.jl
+
+A Julia package for working with objects in fusion categories.
+
+This package provides functionality for defining objects in fusion categories, along with
+their topological data. This includes the fusion rules, the associators, and the braiding.
+In particular, this is the data that is needed to define (symmetric) tensors, which are
+defined over vector spaces graded by these objects. For the full functionality, we refer to
+[TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) and [its
+documentation](https://quantumkithub.github.io/TensorKit.jl/stable/).
+
+Install via the package manager.

docs/src/lib.md

@@ -0,0 +1,5 @@
+# Library documentation
+
+```@autodocs
+Modules = [TensorKitSectors]
+```

src/irreps/znirrep.jl

@@ -7,7 +7,7 @@ const SMALL_ZN_CUTOFF = (typemax(UInt8) + 1) ÷ 2
     Irrep[ℤ{N}](n::Integer)
 
 Represents irreps of the group ``ℤ_N`` for some value of `N`.
-For `N` equals `2`, `3` or `4`, `ℤ{N}` can be replaced by [`ℤ₂`](@ref), [`ℤ₃`](@ref), and [`ℤ₄`](@ref).
+For `N` equals `2`, `3` or `4`, `ℤ{N}` can be replaced by `ℤ₂`, `ℤ₃`, and `ℤ₄`.
 An arbitrary `Integer` `n` can be provided to the constructor, but only the value `mod(n, N)` is relevant.
 
 The type of the stored integer (`UInt8`) requires `N ≤ $SMALL_ZN_CUTOFF`.
@@ -33,7 +33,7 @@ end
     Irrep[ℤ{N}](n::Integer)
 
 Represents irreps of the group ``ℤ_N`` for some value of `N`, which is typically larger than $SMALL_ZN_CUTOFF.
-For smaller values of `N`, the [`ZNIrrep}`](@ref) sector type should be used instead.
+For smaller values of `N`, the [`ZNIrrep`](@ref) sector type should be used instead.
 An arbitrary `Integer` `n` can be provided to the constructor, but only the value `mod(n, N)` is relevant.
 
 The constructor `Irrep[ℤ{N}]` should be preferred, as it will automatically select the most efficient storage type for a given value of `N`.

src/product.jl

@@ -8,7 +8,7 @@ const SectorTuple = Tuple{Vararg{Sector}}
 
 Represents the Deligne tensor product of sectors. The type parameter `T` is a tuple of the
 component sectors. The recommended way to construct a `ProductSector` is using the
-[`deligneproduct`](@ref) (`⊠`) operator on the components.
+[`deligneproduct`](@ref ⊠) (`⊠`) operator on the components.
 """
 struct ProductSector{T <: SectorTuple} <: Sector
     sectors::T