Switch from Pluto notebooks to documenter

.github/workflows/ci.yml

@@ -47,26 +47,23 @@ jobs:
   docs:
     name: Documentation
     runs-on: ubuntu-latest
+    permissions:
+      actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      contents: write
+      statuses: write
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
-
-      - name: Run Pluto notebooks
-        run: julia -e 'using Pkg;
-            Pkg.add("PlutoUI");
-            Pkg.activate("notebooks");
-            Pkg.develop(path=".");
-            Pkg.instantiate();
-            using PlutoSliderServer;
-            for file in readdir("notebooks")
-              endswith(file, ".jl") && PlutoSliderServer.export_notebook(joinpath("notebooks", file))
-            end
-            '
-      - name: Deploy to gh-pages
-        uses: JamesIves/github-pages-deploy-action@releases/v3
-        with:
-            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-            BRANCH: gh-pages
-            FOLDER: .
+      - uses: julia-actions/cache@v2
+      - name: Configure doc environment
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -7,3 +7,5 @@ _local/
 *.log
 *.fdb_latexmk
 .vscode
+/docs/build/
+/docs/src/generated/

Makefile

@@ -0,0 +1,31 @@
+JL = julia --project
+
+default: init test
+
+init:
+	$(JL) -e 'using Pkg; Pkg.precompile(); Pkg.activate("docs"); Pkg.develop(path="."), Pkg.precompile()'
+
+update:
+	$(JL) -e 'using Pkg; Pkg.update(); Pkg.precompile(); Pkg.activate("docs"); Pkg.update(); Pkg.precompile()'
+
+test:
+	$(JL) -e 'using Pkg; Pkg.test()'
+
+coverage:
+	$(JL) -e 'using Pkg; Pkg.test(; coverage=true)'
+
+serve:
+	$(JL) -e 'using Pkg; Pkg.activate("docs"); using LiveServer; servedocs(;skip_dirs=["docs/src/assets", "docs/src/generated"], literate_dir="examples")'
+
+fig:
+	for entry in "docs/src/assets/"*.typ; do \
+		echo compiling $$entry to $${entry%.typ}.pdf; \
+		typst compile $$entry $${entry%.typ}.pdf; \
+		pdf2svg $${entry%.typ}.pdf $${entry%.typ}.svg; \
+	done
+
+clean:
+	rm -rf docs/build
+	find . -name "*.cov" -type f -print0 | xargs -0 /bin/rm -f
+
+.PHONY: init test coverage serve clean update

README.md

@@ -19,30 +19,5 @@
 pkg> add UnitDiskMapping
 ```
 
-## Examples
-
-Please check the following notebooks:
-1. [Unit Disk Mapping](https://queracomputing.github.io/UnitDiskMapping.jl/notebooks/tutorial.html), which contains the examples in ["Quantum Optimization with Arbitrary Connectivity Using Rydberg Atom Arrays"](https://journals.aps.org/prxquantum/abstract/10.1103/PRXQuantum.4.010316):
-    * Reduction from a generic weighted or unweighted maximum independent set (MIS) problem to that on a King's subgraph (KSG).
-    * Reduction from a generic or square-lattice QUBO problem to an MIS problem on a unit-disk grid graph.
-    * Reduction from an integer factorization problem to an MIS problem on a unit-disk grid graph.
-
-2. [Unweighted KSG reduction of the independent set problem](https://queracomputing.github.io/UnitDiskMapping.jl/notebooks/unweighted.html), which contains the unweighted reduction from a general graph to a King's subgraph. It covers all example graphs in paper: "Computer-Assisted Gadget Design and Problem Reduction of Unweighted Maximum Independent Set" (To be published).
-
-![](https://user-images.githubusercontent.com/6257240/198861111-4499c17d-9938-406b-8253-943b01f4633c.png)
-
-To run the notebook locally, you will need to activate and instantiate the local environment that specified in the [`notebooks`](notebooks) directory:
-```bash
-$ cd notebooks
-$ julia --project -e 'using Pkg; Pkg.instantiate()'
-```
-
-To run the notebook, just type in the same terminal:
-```bash
-julia --project -e "import Pluto; Pluto.run()"
-```
-At this point, your browser should automatically launch and display a list of available notebooks you can run. You should just see the notebooks listed.
-
-
 ## Supporting and Citing
 Much of the software in this ecosystem was developed as a part of an academic research project. If you would like to help support it, please star the repository. If you use our software as part of your research, teaching, or other activities, we would like to request you to cite our [work](https://arxiv.org/abs/2209.03965). The [CITATION.bib](CITATION.bib) file in the root of this repository lists the relevant papers.

docs/Project.toml

@@ -0,0 +1,9 @@
+[deps]
+DocThemeIndigo = "8bac0ac5-51bf-41f9-885e-2bf1ac2bec5f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GenericTensorNetworks = "3521c873-ad32-4bb4-b63d-f4f178f42b49"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+LuxorGraphPlot = "1f49bdf2-22a7-4bc4-978b-948dc219fbbc"
+UnitDiskMapping = "1b61a8d9-79ed-4491-8266-ef37f39e1727"

docs/make.jl

@@ -0,0 +1,42 @@
+using UnitDiskMapping
+using Documenter
+using Literate
+using DocThemeIndigo
+
+# Literate
+for each in readdir(pkgdir(UnitDiskMapping, "examples"))
+    input_file = pkgdir(UnitDiskMapping, "examples", each)
+    endswith(input_file, ".jl") || continue
+    @info "building" input_file
+    output_dir = pkgdir(UnitDiskMapping, "docs", "src", "generated")
+    Literate.markdown(input_file, output_dir; name=each[1:end-3], execute=false)
+end
+
+DocMeta.setdocmeta!(UnitDiskMapping, :DocTestSetup, :(using UnitDiskMapping); recursive=true)
+indigo = DocThemeIndigo.install(UnitDiskMapping)
+
+makedocs(;
+    modules=[UnitDiskMapping],
+    authors="GiggleLiu and contributors",
+    sitename="UnitDiskMapping.jl",
+    format=Documenter.HTML(;
+        canonical="https://QuEraComputing.github.io/UnitDiskMapping.jl",
+        edit_link="main",
+        assets=String[indigo],
+    ),
+    doctest = ("doctest=true" in ARGS),
+    pages=[
+        "Home" => "index.md",
+        "Examples" => [
+            "generated/tutorial.md",
+            "generated/unweighted.md"
+        ],
+        "Reference" => "ref.md",
+    ],
+    warnonly=[:missing_docs]
+)
+
+deploydocs(;
+    repo="github.com/QuEraComputing/UnitDiskMapping.jl",
+    devbranch="main",
+)

docs/src/assets/indigo.css

@@ -0,0 +1,88 @@
+@font-face {
+  font-family: JuliaMono;
+  src: local("JuliaMono"), url("https://cdn.jsdelivr.net/gh/cormullion/juliamono/webfonts/JuliaMono-Regular.woff2"); }
+
+html.theme--documenter-dark pre,
+html.theme--documenter-dark code {
+  font-family: "JuliaMono"; }
+
+html:not(.theme--documenter-dark) body #documenter a {
+  color: #4595D1; }
+
+html:not(.theme--documenter-dark) body #documenter a:hover, html:not(.theme--documenter-dark) body #documenter a:focus {
+  color: #194E82; }
+
+html:not(.theme--documenter-dark) body #documenter .docs-sidebar {
+  box-shadow: none;
+  color: #FFFFFF;
+  background-color: #194E82; }
+  html:not(.theme--documenter-dark) body #documenter .docs-sidebar .docs-package-name a, html:not(.theme--documenter-dark) body #documenter .docs-sidebar .docs-package-name a:hover {
+    color: #FFFFFF; }
+  html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu {
+    border-top: none; }
+    html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover, html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover, html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem, html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu .tocitem:hover {
+      color: #FFFFFF;
+      background-color: #4595D1; }
+    html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu .tocitem {
+      color: #FFFFFF;
+      background: none; }
+    html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active {
+      border-top: none;
+      border-bottom: none; }
+      html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal {
+        margin: 0;
+        border-top: none; }
+        html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal li {
+          margin-top: 0; }
+        html:not(.theme--documenter-dark) body #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem {
+          color: #194E82;
+          background-color: #FFFFFF;
+          padding: 0.5em;
+          padding-left: 1em; }
+
+html:not(.theme--documenter-dark) body #documenter article#documenter-page a.docs-heading-anchor {
+  color: #194E82; }
+
+html:not(.theme--documenter-dark) body #documenter pre, html:not(.theme--documenter-dark) body #documenter code {
+  color: inherit;
+  font-family: "JuliaMono"; }
+  html:not(.theme--documenter-dark) body #documenter pre .hljs-meta, html:not(.theme--documenter-dark) body #documenter code .hljs-meta {
+    color: #4595D1; }
+  html:not(.theme--documenter-dark) body #documenter pre .hljs-keyword, html:not(.theme--documenter-dark) body #documenter code .hljs-keyword {
+    color: #194E82; }
+
+.admonition.is-category-terminology {
+  background-color: #FFFEDD;
+  border-color: #FFEC8B; }
+  .admonition.is-category-terminology > .admonition-header {
+    background-color: #FFEC8B;
+    color: black; }
+    .admonition.is-category-terminology > .admonition-header:before {
+      content: "Terminology: ";
+      font-family: inherit;
+      font-weight: bold; }
+
+html.theme--documenter-dark .admonition.is-category-terminology {
+  border-color: #FFEC8B; }
+
+details {
+  padding-left: 1rem;
+  padding-right: 1rem;
+  padding-bottom: 1rem;
+  background: aliceblue; }
+
+html.theme--documenter-dark details {
+  background: #282f2f; }
+
+.video-container {
+  position: relative;
+  width: 100%;
+  padding-bottom: 56.25%; }
+
+.video-container > iframe {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  border: 0; }

docs/src/index.md

@@ -0,0 +1,15 @@
+```@meta
+CurrentModule = UnitDiskMapping
+```
+
+# UnitDiskMapping
+
+Please check the following examples:
+1. [Unit Disk Mapping](@ref), which contains the examples in ["Quantum Optimization with Arbitrary Connectivity Using Rydberg Atom Arrays"](https://journals.aps.org/prxquantum/abstract/10.1103/PRXQuantum.4.010316):
+    * Reduction from a generic weighted or unweighted maximum independent set (MIS) problem to that on a King's subgraph (KSG).
+    * Reduction from a generic or square-lattice QUBO problem to an MIS problem on a unit-disk grid graph.
+    * Reduction from an integer factorization problem to an MIS problem on a unit-disk grid graph.
+
+2. [Unweighted KSG reduction of the independent set problem](@ref), which contains the unweighted reduction from a general graph to a King's subgraph. It covers all example graphs in paper: "Computer-Assisted Gadget Design and Problem Reduction of Unweighted Maximum Independent Set" (To be published).
+
+![](https://user-images.githubusercontent.com/6257240/198861111-4499c17d-9938-406b-8253-943b01f4633c.png)

docs/src/ref.md

@@ -0,0 +1,5 @@
+# Reference
+
+```@autodocs
+Modules = [UnitDiskMapping]
+```