Skip to content

Commit 9776f5f

Browse files
albertomercurioalbertomercurio
authored
Convert Documentation to Vitepress (#287)
1 parent c8c9479 commit 9776f5f

File tree

8 files changed

+400
-37
lines changed

8 files changed

+400
-37
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -21,27 +21,39 @@ on:
2121
- synchronize
2222
- ready_for_review
2323

24+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
25+
permissions:
26+
contents: write
27+
pages: write
28+
id-token: write
29+
statuses: write
30+
31+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
32+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
33+
concurrency:
34+
group: pages
35+
cancel-in-progress: false
36+
2437
jobs:
38+
# Build job
2539
build:
2640
runs-on: ubuntu-latest
27-
permissions:
28-
contents: write
29-
statuses: write
3041
if: ${{ !github.event.pull_request.draft }}
3142
steps:
32-
- uses: actions/checkout@v4
33-
- uses: julia-actions/setup-julia@v2
34-
with:
35-
version: '1'
36-
- uses: julia-actions/cache@v2
37-
- uses: julia-actions/julia-buildpkg@v1
38-
- uses: julia-actions/julia-docdeploy@v1
43+
- name: Checkout
44+
uses: actions/checkout@v4
45+
- name: Setup Julia
46+
uses: julia-actions/setup-julia@v2
47+
- name: Pull Julia cache
48+
uses: julia-actions/cache@v2
49+
- name: Install documentation dependencies
50+
run: julia --project=docs -e 'using Pkg; pkg"dev ."; Pkg.instantiate(); Pkg.precompile(); Pkg.status()'
51+
#- name: Creating new mds from src
52+
- name: Build and deploy docs
53+
uses: julia-actions/julia-docdeploy@v1
3954
env:
40-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
41-
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
42-
- run: |
43-
julia --project=docs -e '
44-
using Documenter: DocMeta, doctest
45-
using QuantumToolbox
46-
DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive=true)
47-
doctest(QuantumToolbox)'
55+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
56+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
57+
GKSwstype: "100" # for Plots.jl plots (if you have them)
58+
JULIA_DEBUG: "Documenter"
59+
DATADEPS_ALWAYS_ACCEPT: true

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
*.jl.cov
55
*.jl.mem
66
Manifest.toml
7-
docs/build/
87

98
.vscode
109
*.json

‎docs/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
build/
2+
node_modules/
3+
package-lock.json
4+
Manifest.toml

‎docs/Project.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,5 @@ BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
33
CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
44
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
55
DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
6+
DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
67
QuantumToolbox = "6c2fb7c5-b903-41d2-bc5e-5a7c320b9fab"

‎docs/make.jl‎

Lines changed: 31 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
using QuantumToolbox
55
using Documenter
6+
using DocumenterVitepress
67
using DocumenterCitations
78

89
DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive = true)
@@ -11,16 +12,16 @@ const DRAFT = false # set `true` to disable cell evaluation
1112

1213
bib = CitationBibliography(joinpath(@__DIR__, "src", "bibliography.bib"), style=:authoryear)
1314

14-
const MathEngine = MathJax3(
15-
Dict(
16-
:loader => Dict("load" => ["[tex]/physics"]),
17-
:tex => Dict(
18-
"inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
19-
"tags" => "ams",
20-
"packages" => ["base", "ams", "autoload", "physics"],
21-
),
22-
)
23-
)
15+
# const MathEngine = MathJax3(
16+
# Dict(
17+
# :loader => Dict("load" => ["[tex]/physics"]),
18+
# :tex => Dict(
19+
# "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
20+
# "tags" => "ams",
21+
# "packages" => ["base", "ams", "autoload", "physics"],
22+
# ),
23+
# )
24+
# )
2425

2526
const PAGES = [
2627
"Getting Started" => [
@@ -71,16 +72,28 @@ makedocs(;
7172
repo = Remotes.GitHub("qutip", "QuantumToolbox.jl"),
7273
sitename = "QuantumToolbox.jl",
7374
pages = PAGES,
74-
format = Documenter.HTML(;
75-
prettyurls = get(ENV, "CI", "false") == "true",
76-
canonical = "https://qutip.github.io/QuantumToolbox.jl",
77-
edit_link = "main",
78-
assets = ["assets/favicon.ico"],
79-
mathengine = MathEngine,
80-
size_threshold_ignore = ["api.md"],
75+
# format = Documenter.HTML(;
76+
# prettyurls = get(ENV, "CI", "false") == "true",
77+
# canonical = "https://qutip.github.io/QuantumToolbox.jl",
78+
# edit_link = "main",
79+
# assets = ["assets/favicon.ico"],
80+
# mathengine = MathEngine,
81+
# size_threshold_ignore = ["api.md"],
82+
# ),
83+
format = DocumenterVitepress.MarkdownVitepress(
84+
repo = "https://qutip.github.io/QuantumToolbox.jl",
85+
# deploy_url = "https://qutip.org/QuantumToolbox.jl/",
8186
),
8287
draft = DRAFT,
8388
plugins = [bib],
8489
)
8590

86-
deploydocs(; repo = "github.com/qutip/QuantumToolbox.jl", devbranch = "main")
91+
# deploydocs(; repo = "github.com/qutip/QuantumToolbox.jl", devbranch = "main")
92+
93+
deploydocs(;
94+
repo = "github.com/qutip/QuantumToolbox.jl",
95+
target = "build", # this is where Vitepress stores its output
96+
devbranch = "main",
97+
branch = "gh-pages",
98+
push_preview = true,
99+
)

‎docs/src/.vitepress/config.mts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import { defineConfig } from 'vitepress'
2+
import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
3+
import mathjax3 from "markdown-it-mathjax3";
4+
import footnote from "markdown-it-footnote";
5+
6+
// https://vitepress.dev/reference/site-config
7+
export default defineConfig({
8+
base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
9+
title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
10+
description: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
11+
lastUpdated: true,
12+
cleanUrls: true,
13+
outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
14+
head: [['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }]],
15+
ignoreDeadLinks: true,
16+
17+
markdown: {
18+
math: true,
19+
config(md) {
20+
md.use(tabsMarkdownPlugin),
21+
md.use(mathjax3),
22+
md.use(footnote)
23+
},
24+
theme: {
25+
light: "github-light",
26+
dark: "github-dark"
27+
}
28+
},
29+
themeConfig: {
30+
outline: 'deep',
31+
logo: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
32+
search: {
33+
provider: 'local',
34+
options: {
35+
detailedView: true
36+
}
37+
},
38+
nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
39+
sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
40+
editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
41+
socialLinks: [
42+
{ icon: 'github', link: 'REPLACE_ME_DOCUMENTER_VITEPRESS' }
43+
],
44+
footer: {
45+
message: 'Made with <a href="https://luxdl.github.io/DocumenterVitepress.jl/dev/" target="_blank"><strong>DocumenterVitepress.jl</strong></a><br>',
46+
copyright: `© Copyright ${new Date().getUTCFullYear()}.`
47+
}
48+
}
49+
})

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// .vitepress/theme/index.ts
2+
import { h } from 'vue'
3+
import type { Theme } from 'vitepress'
4+
import DefaultTheme from 'vitepress/theme'
5+
6+
import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
7+
import './style.css'
8+
9+
export default {
10+
extends: DefaultTheme,
11+
Layout() {
12+
return h(DefaultTheme.Layout, null, {
13+
// https://vitepress.dev/guide/extending-default-theme#layout-slots
14+
})
15+
},
16+
enhanceApp({ app, router, siteData }) {
17+
enhanceAppWithTabs(app)
18+
}
19+
} satisfies Theme

0 commit comments

Comments
 (0)