Vitepress documentation

.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

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

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

@@ -25,3 +25,23 @@ Run the following command:
 ```shell
 julia --project=docs docs/make.jl
 ```
+
+# How to start a local Vitepress site ?
+
+> [!NOTE]
+> You need to install `Node.js` and `npm` first. 
+
+Enter `docs` directory first:
+```shell
+cd /path/to/QuantumToolbox.jl/docs
+```
+
+Install `npm` dependencies:
+```shell
+npm i
+```
+
+Run the following command:
+```shell
+npm 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 = "https://qutip.github.io/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,61 @@
+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,
+        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://luxdl.github.io/DocumenterVitepress.jl/dev/" target="_blank"><strong>DocumenterVitepress.jl</strong></a><br>',
+            copyright: `© Copyright ${new Date().getUTCFullYear()}.`
+        }
+    }
+})

docs/src/.vitepress/theme/VersionPicker.vue

@@ -0,0 +1,64 @@
+<!-- Adapted from https://github.com/MakieOrg/Makie.jl/blob/master/docs/src/.vitepress/theme/VersionPicker.vue -->
+
+<script setup lang="ts">
+import { computed, ref, onMounted } from 'vue'
+import { useRoute } from 'vitepress'
+import VPNavBarMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavBarMenuGroup.vue'
+import VPNavScreenMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavScreenMenuGroup.vue'
+
+const props = defineProps<{
+  screenMenu?: boolean
+}>()
+
+const route = useRoute()
+
+const versions = ref([]);
+const currentVersion = ref('Versions');
+
+const waitForGlobalDocumenterVars = () => {
+    return new Promise((resolve) => {
+    const checkInterval = setInterval(() => {
+        if (window.DOC_VERSIONS && window.DOCUMENTER_CURRENT_VERSION) {
+        clearInterval(checkInterval);
+        resolve({
+            versions: window.DOC_VERSIONS,
+            currentVersion: window.DOCUMENTER_CURRENT_VERSION
+        });
+        }
+    }, 100); // Check every 100ms
+    });
+};
+
+onMounted(async () => {
+    const globalvars = await waitForGlobalDocumenterVars();
+    versions.value = globalvars.versions.map((v) => {
+        return {text: v, link: `${window.location.origin}/${v}/`}
+    });
+    currentVersion.value = globalvars.currentVersion;
+});
+
+</script>
+
+<template>
+  <VPNavBarMenuGroup
+    v-if="!screenMenu"
+    :item="{ text: currentVersion, items: versions }"
+    class="VPVersionPicker"
+  />
+  <VPNavScreenMenuGroup
+    v-else
+    :text="currentVersion"
+    :items="versions"
+    class="VPVersionPicker"
+  />
+</template>
+
+<style scoped>
+.VPVersionPicker :deep(button .text) {
+  color: var(--vp-c-text-1) !important;
+}
+
+.VPVersionPicker:hover :deep(button .text) {
+  color: var(--vp-c-text-2) !important;
+}
+</style>

docs/src/.vitepress/theme/index.ts

@@ -0,0 +1,21 @@
+// .vitepress/theme/index.ts
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import VersionPicker from "./VersionPicker.vue"
+
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+import './style.css'
+
+export default {
+    extends: DefaultTheme,
+    Layout() {
+        return h(DefaultTheme.Layout, null, {
+            // https://vitepress.dev/guide/extending-default-theme#layout-slots
+        })
+    },
+    enhanceApp({ app, router, siteData }) {
+        enhanceAppWithTabs(app);
+        app.component('VersionPicker', VersionPicker);
+    }
+} satisfies Theme