diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index beaa3fc02..87d82251a 100644
--- a/.github/workflows/documentation.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index edb4c3a5e..900000a03 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,6 @@
*.jl.cov
*.jl.mem
Manifest.toml
-docs/build/
.vscode
*.json
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..778ffdc18
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,4 @@
+build/
+node_modules/
+package-lock.json
+Manifest.toml
diff --git a/docs/Project.toml b/docs/Project.toml
index b61136e89..ef98b807e 100644
--- a/docs/Project.toml
+++ b/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"
diff --git a/docs/make.jl b/docs/make.jl
index 375ffec53..9e69887e4 100644
--- a/docs/make.jl
+++ b/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,
+)
diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
new file mode 100644
index 000000000..38dbec64f
--- /dev/null
+++ b/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 DocumenterVitepress.jl
',
+ copyright: `© Copyright ${new Date().getUTCFullYear()}.`
+ }
+ }
+})
diff --git a/docs/src/.vitepress/theme/index.ts b/docs/src/.vitepress/theme/index.ts
new file mode 100644
index 000000000..1072d80a5
--- /dev/null
+++ b/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
diff --git a/docs/src/.vitepress/theme/style.css b/docs/src/.vitepress/theme/style.css
new file mode 100644
index 000000000..2617bf119
--- /dev/null
+++ b/docs/src/.vitepress/theme/style.css
@@ -0,0 +1,266 @@
+/* Customize default theme styling by overriding CSS variables:
+https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/* Layouts */
+
+/*
+ :root {
+ --vp-layout-max-width: 1440px;
+} */
+
+.VPHero .clip {
+ white-space: pre;
+ max-width: 500px;
+}
+
+/* Fonts */
+
+@font-face {
+ font-family: JuliaMono-Regular;
+ src: url("https://cdn.jsdelivr.net/gh/cormullion/juliamono/webfonts/JuliaMono-Regular.woff2");
+}
+
+:root {
+ /* Typography */
+ --vp-font-family-base: "Barlow", "Inter var experimental", "Inter var",
+ -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu,
+ Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
+
+ /* Code Snippet font */
+ --vp-font-family-mono: JuliaMono-Regular, monospace;
+
+}
+
+/*
+ Disable contextual alternates (kind of like ligatures but different) in monospace,
+ which turns `/>` to an up arrow and `|>` (the Julia pipe symbol) to an up arrow as well.
+ This is pretty bad for Julia folks reading even though copy+paste retains the same text.
+ */
+/* Target elements with class 'mono' */
+.mono-no-substitutions {
+ font-family: "JuliaMono-Light", monospace;
+ font-feature-settings: "calt" off;
+}
+
+/* Alternatively, you can use the following if you prefer: */
+.mono-no-substitutions-alt {
+ font-family: "JuliaMono-Light", monospace;
+ font-variant-ligatures: none;
+}
+
+/* If you want to apply this globally to all monospace text: */
+pre,
+code {
+ font-family: "JuliaMono-Light", monospace;
+ font-feature-settings: "calt" off;
+}
+
+/* Colors */
+
+:root {
+ --julia-blue: #4063D8;
+ --julia-purple: #9558B2;
+ --julia-red: #CB3C33;
+ --julia-green: #389826;
+
+ --vp-c-brand: #389826;
+ --vp-c-brand-light: #3dd027;
+ --vp-c-brand-lighter: #9499ff;
+ --vp-c-brand-lightest: #bcc0ff;
+ --vp-c-brand-dark: #535bf2;
+ --vp-c-brand-darker: #454ce1;
+ --vp-c-brand-dimm: #212425;
+}
+
+/* Component: Button */
+
+:root {
+ --vp-button-brand-border: var(--vp-c-brand-light);
+ --vp-button-brand-text: var(--vp-c-white);
+ --vp-button-brand-bg: var(--vp-c-brand);
+ --vp-button-brand-hover-border: var(--vp-c-brand-light);
+ --vp-button-brand-hover-text: var(--vp-c-white);
+ --vp-button-brand-hover-bg: var(--vp-c-brand-light);
+ --vp-button-brand-active-border: var(--vp-c-brand-light);
+ --vp-button-brand-active-text: var(--vp-c-white);
+ --vp-button-brand-active-bg: var(--vp-button-brand-bg);
+}
+
+/* Component: Home */
+
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(120deg,
+ #9558B2 30%,
+ #CB3C33);
+
+ --vp-home-hero-image-background-image: linear-gradient(-45deg,
+ #9558B2 30%,
+ #389826 30%,
+ #CB3C33);
+ --vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+ :root {
+ --vp-home-hero-image-filter: blur(56px);
+ }
+}
+
+@media (min-width: 960px) {
+ :root {
+ --vp-home-hero-image-filter: blur(72px);
+ }
+}
+
+/* Component: Custom Block */
+
+:root.dark {
+ --vp-custom-block-tip-border: var(--vp-c-brand);
+ --vp-custom-block-tip-text: var(--vp-c-brand-lightest);
+ --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+
+ /* // Tweak the color palette for blacks and dark grays */
+ --vp-c-black: hsl(220 20% 9%);
+ --vp-c-black-pure: hsl(220, 24%, 4%);
+ --vp-c-black-soft: hsl(220 16% 13%);
+ --vp-c-black-mute: hsl(220 14% 17%);
+ --vp-c-gray: hsl(220 8% 56%);
+ --vp-c-gray-dark-1: hsl(220 10% 39%);
+ --vp-c-gray-dark-2: hsl(220 12% 28%);
+ --vp-c-gray-dark-3: hsl(220 12% 23%);
+ --vp-c-gray-dark-4: hsl(220 14% 17%);
+ --vp-c-gray-dark-5: hsl(220 16% 13%);
+
+ /* // Backgrounds */
+ /* --vp-c-bg: hsl(240, 2%, 11%); */
+ --vp-custom-block-info-bg: hsl(220 14% 17%);
+ /* --vp-c-gutter: hsl(220 20% 9%);
+
+ --vp-c-bg-alt: hsl(220 20% 9%);
+ --vp-c-bg-soft: hsl(220 14% 17%);
+ --vp-c-bg-mute: hsl(220 12% 23%);
+ */
+}
+
+/* Component: Algolia */
+
+.DocSearch {
+ --docsearch-primary-color: var(--vp-c-brand) !important;
+}
+
+/* Component: MathJax */
+
+mjx-container>svg {
+ display: block;
+ margin: auto;
+}
+
+mjx-container {
+ padding: 0.5rem 0;
+}
+
+mjx-container {
+ display: inline;
+ margin: auto 2px -2px;
+}
+
+mjx-container>svg {
+ margin: auto;
+ display: inline-block;
+}
+
+/**
+ * Colors links
+ * -------------------------------------------------------------------------- */
+
+:root {
+ --vp-c-brand-1: #CB3C33;
+ --vp-c-brand-2: #CB3C33;
+ --vp-c-brand-3: #CB3C33;
+ --vp-c-sponsor: #ca2971;
+ --vitest-c-sponsor-hover: #c13071;
+}
+
+.dark {
+ --vp-c-brand-1: #91dd33;
+ --vp-c-brand-2: #91dd33;
+ --vp-c-brand-3: #91dd33;
+ --vp-c-sponsor: #91dd33;
+ --vitest-c-sponsor-hover: #e51370;
+}
+
+/**
+ * Change images from light to dark theme
+ * -------------------------------------------------------------------------- */
+
+:root:not(.dark) .dark-only {
+ display: none;
+}
+
+:root:is(.dark) .light-only {
+ display: none;
+}
+
+/* https://bddxg.top/article/note/vitepress优化/一些细节上的优化.html#文档页面调整-加宽 */
+
+.VPDoc.has-aside .content-container {
+ max-width: 100% !important;
+}
+
+.aside {
+ max-width: 200px !important;
+ padding-left: 0 !important;
+}
+
+.VPDoc {
+ padding-top: 15px !important;
+ padding-left: 5px !important;
+
+}
+
+/* This one does the right menu */
+
+.VPDocOutlineItem li {
+ text-overflow: ellipsis;
+ overflow: hidden;
+ white-space: nowrap;
+ max-width: 200px;
+}
+
+.VPNavBar .title {
+ text-overflow: ellipsis;
+ overflow: hidden;
+ white-space: nowrap;
+}
+
+@media (max-width: 960px) {
+ .VPDoc {
+ padding-left: 25px !important;
+ }
+}
+
+/* This one does the left menu */
+
+/* .VPSidebarItem .VPLink p {
+ text-overflow: ellipsis;
+ overflow: hidden;
+ white-space: nowrap;
+ max-width: 200px;
+ } */
+
+
+/* Component: Docstring Custom Block */
+
+.jldocstring.custom-block {
+ border: 1px solid var(--vp-c-gray-2);
+ color: var(--vp-c-text-1)
+}
+
+.jldocstring.custom-block summary {
+ font-weight: 700;
+ cursor: pointer;
+ user-select: none;
+ margin: 0 0 8px;
+}
\ No newline at end of file