Convert Documentation to Vitepress

.github/workflows/documentation.yml

@@ -21,27 +21,39 @@ 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
-      - uses: julia-actions/setup-julia@v2
-        with:
-          version: '1'
-      - uses: julia-actions/cache@v2
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@v2
+      - name: Pull Julia cache
+        uses: julia-actions/cache@v2
+      - name: Install documentation dependencies
+        run: julia --project=docs -e 'using Pkg; pkg"dev ."; Pkg.instantiate(); Pkg.precompile(); Pkg.status()'
+      #- name: Creating new mds from src
+      - name: Build and deploy docs
+        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
+          GKSwstype: "100" # for Plots.jl plots (if you have them)
+          JULIA_DEBUG: "Documenter"
+          DATADEPS_ALWAYS_ACCEPT: true

.gitignore

@@ -4,7 +4,6 @@
 *.jl.cov
 *.jl.mem
 Manifest.toml
-docs/build/
 
 .vscode
 *.json

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/make.jl

@@ -3,6 +3,7 @@
 
 using QuantumToolbox
 using Documenter
+using DocumenterVitepress
 using DocumenterCitations
 
 DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive = true)
@@ -11,16 +12,16 @@ 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"],
-        ),
-    )
-)
+# const MathEngine = MathJax3(
+#     Dict(
+#         :loader => Dict("load" => ["[tex]/physics"]),
+#         :tex => Dict(
+#             "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
+#             "tags" => "ams",
+#             "packages" => ["base", "ams", "autoload", "physics"],
+#         ),
+#     )
+# )
 
 const PAGES = [
     "Getting Started" => [
@@ -71,16 +72,28 @@ 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 = 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",
+        # deploy_url = "https://qutip.org/QuantumToolbox.jl/",
     ),
     draft = DRAFT,
     plugins = [bib],
 )
 
-deploydocs(; repo = "github.com/qutip/QuantumToolbox.jl", devbranch = "main")
+# 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/src/.vitepress/config.mts

@@ -0,0 +1,49 @@
+import { defineConfig } from 'vitepress'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
+import mathjax3 from "markdown-it-mathjax3";
+import footnote from "markdown-it-footnote";
+
+// 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: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+        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/index.ts

@@ -0,0 +1,19 @@
+// .vitepress/theme/index.ts
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+
+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)
+    }
+} satisfies Theme