Update documentation and add automation for previews

.github/workflows/DocumentationCleanup.yml

@@ -0,0 +1,33 @@
+name: Doc 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@v4
+        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 "documenter@juliadocs.github.io"
+              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/DocumentationPreview.yml

@@ -0,0 +1,17 @@
+name: Docs 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/TensorKitTensors.jl/previews/PR${{ github.event.number }}/)'
+          comment-tag: 'preview-doc'

README.md

@@ -8,10 +8,14 @@
 
 This is a small package that aims to provide several commonly used tensors for TensorKit, with various symmetries.
 For a full list of implemented tensors, see the [documentation](https://QuantumKitHub.github.io/TensorKitTensors.jl/stable/).
+If there are any tensors you would like to see added, feel free to open an issue or a pull request.
 
 ## Installation
 
+Installation is done via the Julia package manager.
+You can install it by running the following command in the Julia REPL:
+
 ```julia
-julia> import Pkg
-julia> Pkg.add("https://github.com/QuantumKitHub/TensorKitTensors.jl")
+julia> ]
+pkg> add TensorKitTensors
 ```

docs/make.jl

@@ -4,6 +4,8 @@ using Documenter
 DocMeta.setdocmeta!(TensorKitTensors, :DocTestSetup, :(using TensorKitTensors);
                     recursive=true)
 
+operatorpages = ["spinoperators.md", "bosonoperators.md", "fermionoperators.md",
+                 "tjoperators.md", "hubbardoperators.md"]
 makedocs(;
          modules=[TensorKitTensors],
          authors="QuantumKitHub",
@@ -12,6 +14,8 @@ makedocs(;
                                 canonical="https://QuantumKitHub.github.io/TensorKitTensors.jl",
                                 edit_link="main",
                                 assets=String[],),
-         pages=["Home" => "index.md"],)
+         pages=["Home" => "index.md", "Operators" => operatorpages],)
 
-deploydocs(; repo="github.com/QuantumKitHub/TensorKitTensors.jl", devbranch="main")
+deploydocs(; repo="github.com/QuantumKitHub/TensorKitTensors.jl",
+           devbranch="main",
+           push_preview=true)

docs/src/bosonoperators.md

@@ -0,0 +1,9 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Boson operators
+
+```@autodocs
+Modules = [TensorKitTensors.BosonOperators]
+```

docs/src/fermionoperators.md

@@ -0,0 +1,9 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Fermion operators
+
+```@autodocs
+Modules = [TensorKitTensors.FermionOperators]
+```

docs/src/hubbardoperators.md

@@ -0,0 +1,9 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Hubbard operators
+
+```@autodocs
+Modules = [TensorKitTensors.HubbardOperators]
+```

docs/src/index.md

@@ -5,10 +5,8 @@ CurrentModule = TensorKitTensors
 # TensorKitTensors
 
 Documentation for [TensorKitTensors](https://github.com/QuantumKitHub/TensorKitTensors.jl).
+This is a lightweight package that defines several commonly used tensors for TensorKit, with various symmetries.
 
-```@index
-```
-
-```@autodocs
-Modules = [TensorKitTensors, TensorKitTensors.SpinOperators, TensorKitTensors.BosonOperators, TensorKitTensors.HubbardOperators, TensorKitTensors.TJOperators, TensorKitTensors.FermionOperators]
+```@contents
+Pages = Main.operatorpages
 ```

docs/src/spinoperators.md

@@ -0,0 +1,9 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Spin operators
+
+```@autodocs
+Modules = [TensorKitTensors.SpinOperators]
+```

docs/src/tjoperators.md

@@ -0,0 +1,9 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# TJ operators
+
+```@autodocs
+Modules = [TensorKitTensors.TJOperators]
+```