qutip · ytdHuang · May 16, 2025 · May 15, 2025 · May 16, 2025 · May 16, 2025
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -21,6 +21,9 @@ on:
       - synchronize
       - ready_for_review
 
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: write

diff --git a/Makefile b/Makefile
@@ -19,7 +19,6 @@ docs:
 	${JULIA} --project=docs docs/make.jl
 
 vitepress:
-	npm --prefix docs i
 	npm --prefix docs run docs:dev
 
 all: setup format changelog test docs vitepress

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -6,3 +6,6 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 QuantumToolbox = "6c2fb7c5-b903-41d2-bc5e-5a7c320b9fab"
+
+[compat]
+DocumenterVitepress = "0.2"
diff --git a/docs/README.md b/docs/README.md
@@ -3,20 +3,21 @@
 ## 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).
+The document pages will be generated in the directory: `/path/to/QuantumToolbox.jl/docs/build/1/` (which is ignored by git).
 
 ## Method 1: Run with `make` command
 Run the following command to instantiate and build the documentation:
+> [!NOTE]
+> You need to install `Node.js` and `npm` first.
 ```shell
 make docs
 ```
 
-Run the following command to start Vitepress site of documentation:
-> [!NOTE]
-> You need to install `Node.js` and `npm` first.
+Run the following command to start a local Vitepress site:
 ```shell
 make vitepress
 ```
+This will start a local Vitepress site of documentation at [http://localhost:5173](http://localhost:5173) in your computer.
 
 ## Method 2: Run commands manually
 
@@ -29,20 +30,15 @@ julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.in
 
 ### Build Documentation
 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
+julia --project=docs docs/make.jl
 ```
 
+### Start a local Vitepress site
 Run the following command:
 ```shell
 npm --prefix docs run docs:dev
-```
+```
+This will start a local Vitepress site of documentation at [http://localhost:5173](http://localhost:5173) in your computer.
diff --git a/docs/make.jl b/docs/make.jl
@@ -46,8 +46,8 @@ const PAGES = [
     ],
     "Users Guide" => [
         "Basic Operations on Quantum Objects" => [
-            "users_guide/QuantumObject/QuantumObject.md",
-            "users_guide/QuantumObject/QuantumObject_functions.md",
+            "Quantum Objects (Qobj)" => "users_guide/QuantumObject/QuantumObject.md",
+            "Functions operating on Qobj" => "users_guide/QuantumObject/QuantumObject_functions.md",
         ],
         "Manipulating States and Operators" => "users_guide/states_and_operators.md",
         "Tensor Products and Partial Traces" => "users_guide/tensor.md",
@@ -66,8 +66,8 @@ const PAGES = [
         "Two-time correlation functions" => "users_guide/two_time_corr_func.md",
         "QuantumToolbox Settings" => "users_guide/settings.md",
         "Extensions" => [
-            "users_guide/extensions/cuda.md",
-            "users_guide/extensions/cairomakie.md",
+            "Extension for CUDA.jl" => "users_guide/extensions/cuda.md",
+            "Extension for the Makie.jl ecosystem" => "users_guide/extensions/cairomakie.md",
         ],
     ],
     "Resources" => [
@@ -90,15 +90,17 @@ makedocs(;
     pages = PAGES,
     format = DocumenterVitepress.MarkdownVitepress(
         repo = "github.com/qutip/QuantumToolbox.jl",
+        devbranch = "main",
+        devurl = "dev",
     ),
     draft = DRAFT,
     doctest = DOCTEST,
     plugins = [bib],
 )
 
-deploydocs(;
+DocumenterVitepress.deploydocs(;
     repo = "github.com/qutip/QuantumToolbox.jl",
-    target = "build", # this is where Vitepress stores its output
+    target = joinpath(@__DIR__, "build"),
     devbranch = "main",
     branch = "gh-pages",
     push_preview = true,

diff --git a/docs/package.json b/docs/package.json
@@ -5,11 +5,11 @@
     "docs:preview": "vitepress preview build/.documenter"
   },
   "dependencies": {
-    "@shikijs/transformers": "^1.1.7",
+    "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.14.0",
     "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"
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-tabs": "^0.6.0"
   }
 }
diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
@@ -2,9 +2,16 @@ import { defineConfig } from 'vitepress'
 import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
 import mathjax3 from "markdown-it-mathjax3";
 import footnote from "markdown-it-footnote";
+import path from 'path'
+
+function getBaseRepository(base: string): string {
+  if (!base || base === '/') return '/';
+  const parts = base.split('/').filter(Boolean);
+  return parts.length > 0 ? `/${parts[0]}/` : '/';
+}
 
 const baseTemp = {
-    base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
 }
 
 const navTemp = {
@@ -22,55 +29,78 @@ const nav = [
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-    base: baseTemp.base,
-    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: '/QuantumToolbox.jl/favicon.ico' }],
-        ['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }],
-        ['script', {src: `/QuantumToolbox.jl/versions.js`}],
-        ['script', {src: `${baseTemp.base}siteinfo.js`}]
-    ],
-    ignoreDeadLinks: true,
-
-    markdown: {
-        math: true,
+  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: '/QuantumToolbox.jl/favicon.ico' }],
+    ['script', {src: `${getBaseRepository(baseTemp.base)}versions.js`}],
+    // ['script', {src: '/versions.js'], for custom domains, I guess if deploy_url is available.
+    ['script', {src: `${baseTemp.base}siteinfo.js`}]
+  ],
+
+  vite: {
+    define: {
+      __DEPLOY_ABSPATH__: JSON.stringify('REPLACE_ME_DOCUMENTER_VITEPRESS_DEPLOY_ABSPATH'),
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, '../components')
+      }
+    },
+    optimizeDeps: {
+      exclude: [ 
+        '@nolebase/vitepress-plugin-enhanced-readabilities/client',
+        'vitepress',
+        '@nolebase/ui',
+      ], 
+    }, 
+    ssr: { 
+      noExternal: [ 
+        // If there are other packages that need to be processed by Vite, you can add them here.
+        '@nolebase/vitepress-plugin-enhanced-readabilities',
+        '@nolebase/ui',
+      ], 
+    },
+  },
+  markdown: {
+    math: true,
 
-        // options for @mdit-vue/plugin-toc
-        // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
-        toc: { level: [2, 3, 4] }, // for API page, triggered by: [[toc]]
+    // options for @mdit-vue/plugin-toc
+    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
+    toc: { level: [2, 3, 4] }, // for API page, triggered by: [[toc]]
 
-        config(md) {
-            md.use(tabsMarkdownPlugin),
-                md.use(mathjax3),
-                md.use(footnote)
-        },
-        theme: {
-            light: "github-light",
-            dark: "github-dark"
-        }
+    config(md) {
+      md.use(tabsMarkdownPlugin),
+      md.use(mathjax3),
+      md.use(footnote)
     },
-    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>.`
-        }
+    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>.`
+    }
+  }
 })