Vitepress documentation (#288)

Author: ytdHuang

.github/workflows/documentation.yml

@@ -21,12 +21,23 @@ on:
       - synchronize
       - ready_for_review
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+  statuses: write
+        
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
+  # Build job
   build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      statuses: write
     if: ${{ !github.event.pull_request.draft }}
     steps:
       - uses: actions/checkout@v4
@@ -37,11 +48,8 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-docdeploy@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-      - run: |
-          julia --project=docs -e '
-            using Documenter: DocMeta, doctest
-            using QuantumToolbox
-            DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive=true)
-            doctest(QuantumToolbox)'
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          JULIA_DEBUG: "Documenter"
+          DATADEPS_ALWAYS_ACCEPT: true
+          # GKSwstype: "100" # for Plots.jl plots (if you have them)

.gitignore

@@ -4,10 +4,10 @@
 *.jl.cov
 *.jl.mem
 Manifest.toml
-docs/build/
 
 .vscode
-*.json
+
+benchmarks/benchmarks_output.json
 
 .ipynb_checkpoints
 *.ipynb

Makefile

@@ -12,13 +12,18 @@ docs:
 	${JULIA} --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
 	${JULIA} --project=docs docs/make.jl
 
-all: format test docs
+vitepress:
+	npm --prefix docs i
+	npm --prefix docs run docs:dev
+
+all: format test docs vitepress
 
 help:
 	@echo "The following make commands are available:"
 	@echo " - make format: format codes with JuliaFormatter"
 	@echo " - make test: run the tests"
 	@echo " - make docs: instantiate and build the documentation"
+	@echo " - make vitepress: start Vitepress site of documentation"
 	@echo " - make all: run every commands in the above order"
 
-.PHONY: default format test docs all help
+.PHONY: default format test docs vitepress all help

README.md

@@ -1,6 +1,6 @@
 <!-- Logo -->
 <div align="center">
-  <img src="./docs/src/assets/logo.png" alt="QuantumToolbox.jl logo" width="150">
+  <img src="./docs/src/public/logo.png" alt="QuantumToolbox.jl logo" width="150">
 </div>
 
 # QuantumToolbox.jl
@@ -65,7 +65,7 @@ QuantumToolbox.jl is equipped with a robust set of features:
 
 - **Quantum State and Operator Manipulation:** Easily handle quantum states and operators with a rich set of tools, with the same functionalities as QuTiP.
 - **Dynamical Evolution:** Advanced solvers for time evolution of quantum systems, thanks to the powerful [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) package.
-- **GPU Computing:** Leverage GPU resources for high-performance computing. For example, you run the master equation directly on the GPU with the same syntax as the CPU case.
+- **GPU Computing:** Leverage GPU resources for high-performance computing. Simulate quantum dynamics directly on the GPU with the same syntax as the CPU case.
 - **Distributed Computing:** Distribute the computation over multiple nodes (e.g., a cluster). For example, you can run hundreds of quantum trajectories in parallel on a cluster, with, again, the same syntax as the simple case.
 - **Easy Extension:** Easily extend the package, taking advantage of the Julia language features, like multiple dispatch and metaprogramming.
 

docs/.gitignore

@@ -0,0 +1,4 @@
+build/
+node_modules/
+package-lock.json
+Manifest.toml

docs/Project.toml

@@ -3,4 +3,5 @@ BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 QuantumToolbox = "6c2fb7c5-b903-41d2-bc5e-5a7c320b9fab"

docs/README.md

@@ -1,17 +1,24 @@
-# How to build documentation locally ?
+# How to build documentation and start Vitepress site locally ?
 
 ## Working Directory
 All the commands should be run under the root folder of the package: `/path/to/QuantumToolbox.jl/`
 
 The document pages will be generated in the directory: `/path/to/QuantumToolbox.jl/docs/build/` (which is ignored by git).
 
 ## Method 1: Run with `make` command
-Run the following command:
+Run the following command to instantiate and build the documentation:
 ```shell
 make docs
 ```
 
-## Method 2: Run `julia` command manually
+Run the following command to start Vitepress site of documentation:
+> [!NOTE]
+> You need to install `Node.js` and `npm` first.
+```shell
+make vitepress
+```
+
+## Method 2: Run commands manually
 
 ### Build Pkg
 Run the following command:
@@ -25,3 +32,17 @@ Run the following command:
 ```shell
 julia --project=docs docs/make.jl
 ```
+
+### Start a local Vitepress site
+> [!NOTE]
+> You need to install `Node.js` and `npm` first.
+
+Install `npm` dependencies:
+```shell
+npm --prefix docs i
+```
+
+Run the following command:
+```shell
+npm --prefix docs run docs:dev
+```

docs/make.jl

@@ -3,28 +3,22 @@
 
 using QuantumToolbox
 using Documenter
+using DocumenterVitepress
 using DocumenterCitations
 
 DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive = true)
 
 const DRAFT = false # set `true` to disable cell evaluation
 
-bib = CitationBibliography(joinpath(@__DIR__, "src", "bibliography.bib"), style=:authoryear)
-
-const MathEngine = MathJax3(
-    Dict(
-        :loader => Dict("load" => ["[tex]/physics"]),
-        :tex => Dict(
-            "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
-            "tags" => "ams",
-            "packages" => ["base", "ams", "autoload", "physics"],
-        ),
-    )
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "resources", "bibliography.bib"), 
+    style=:authoryear,
 )
 
 const PAGES = [
+    "Home" => "index.md",
     "Getting Started" => [
-        "Introduction" => "index.md",
+        "Brief Example" => "getting_started.md",
         "Key differences from QuTiP" => "qutip_differences.md",
         "The Importance of Type-Stability" => "type_stability.md",
         # "Cite QuantumToolbox.jl" => "cite.md",
@@ -60,9 +54,11 @@ const PAGES = [
             "tutorials/logo.md",
         ],
     ],
-    "API" => "api.md",
-    "Bibliography" => "bibliography.md",
-    # "Change Log" => "changelog.md",
+    "Resources" => [
+        "API" => "resources/api.md",
+        # "Change Log" => "resources/changelog.md",
+        "Bibliography" => "resources/bibliography.md",
+    ],
 ]
 
 makedocs(;
@@ -71,16 +67,17 @@ makedocs(;
     repo = Remotes.GitHub("qutip", "QuantumToolbox.jl"),
     sitename = "QuantumToolbox.jl",
     pages = PAGES,
-    format = Documenter.HTML(;
-        prettyurls = get(ENV, "CI", "false") == "true",
-        canonical = "https://qutip.github.io/QuantumToolbox.jl",
-        edit_link = "main",
-        assets = ["assets/favicon.ico"],
-        mathengine = MathEngine,
-        size_threshold_ignore = ["api.md"],
+    format = DocumenterVitepress.MarkdownVitepress(
+        repo = "github.com/qutip/QuantumToolbox.jl",
     ),
     draft = DRAFT,
     plugins = [bib],
 )
 
-deploydocs(; repo = "github.com/qutip/QuantumToolbox.jl", devbranch = "main")
+deploydocs(;
+    repo = "github.com/qutip/QuantumToolbox.jl",
+    target = "build", # this is where Vitepress stores its output
+    devbranch = "main",
+    branch = "gh-pages",
+    push_preview = true,
+)

docs/package.json

@@ -0,0 +1,15 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev build/.documenter",
+    "docs:build": "vitepress build build/.documenter",
+    "docs:preview": "vitepress preview build/.documenter"
+  },
+  "dependencies": {
+    "@shikijs/transformers": "^1.1.7",
+    "markdown-it": "^14.1.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-mathjax3": "^4.3.2",
+    "vitepress": "^1.1.4",
+    "vitepress-plugin-tabs": "^0.5.0"
+  }
+}

docs/src/.vitepress/config.mts

@@ -0,0 +1,66 @@
+import { defineConfig } from 'vitepress'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
+import mathjax3 from "markdown-it-mathjax3";
+import footnote from "markdown-it-footnote";
+
+const navTemp = {
+  nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+}
+
+const nav = [
+  ...navTemp.nav,
+  { text: 'Benchmarks', link: 'https://qutip.org/QuantumToolbox.jl/benchmarks/' },
+  {
+    component: 'VersionPicker'
+  }
+]
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+    base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+    title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    description: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    lastUpdated: true,
+    cleanUrls: true,
+    outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
+    head: [['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }]],
+    ignoreDeadLinks: true,
+
+    markdown: {
+        math: true,
+
+        // options for @mdit-vue/plugin-toc
+        // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
+        toc: { level: [1, 2] },
+
+        config(md) {
+            md.use(tabsMarkdownPlugin),
+                md.use(mathjax3),
+                md.use(footnote)
+        },
+        theme: {
+            light: "github-light",
+            dark: "github-dark"
+        }
+    },
+    themeConfig: {
+        outline: 'deep',
+        logo: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+        search: {
+            provider: 'local',
+            options: {
+                detailedView: true
+            }
+        },
+        nav,
+        sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+        editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+        socialLinks: [
+            { icon: 'github', link: 'REPLACE_ME_DOCUMENTER_VITEPRESS' }
+        ],
+        footer: {
+            message: 'Made with <a href="https://documenter.juliadocs.org/stable/" target="_blank"><strong>Documenter.jl</strong></a>, <a href="https://vitepress.dev" target="_blank"><strong>VitePress</strong></a> and <a href="https://luxdl.github.io/DocumenterVitepress.jl/stable" target="_blank"><strong>DocumenterVitepress.jl</strong></a><br>Released under the BSD 3-Clause License. Powered by the <a href="https://www.julialang.org" target="_blank">Julia Programming Language</a>.<br>',
+            copyright: `© Copyright ${new Date().getUTCFullYear()} <a href="https://qutip.org/" target="_blank"><strong>QuTiP.org</strong></a>.`
+        }
+    }
+})