Skip to content

Commit

Permalink
Vitepress documentation (#288)
Browse files Browse the repository at this point in the history
  • Loading branch information
ytdHuang authored Nov 11, 2024
2 parents ca872f6 + cad8e14 commit a483e6f
Show file tree
Hide file tree
Showing 26 changed files with 711 additions and 186 deletions.
30 changes: 19 additions & 11 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
*.jl.cov
*.jl.mem
Manifest.toml
docs/build/

.vscode
*.json

benchmarks/benchmarks_output.json

.ipynb_checkpoints
*.ipynb
9 changes: 7 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,18 @@ docs:
${JULIA} --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
${JULIA} --project=docs docs/make.jl

all: format test docs
vitepress:
npm --prefix docs i
npm --prefix docs run docs:dev

all: format test docs vitepress

help:
@echo "The following make commands are available:"
@echo " - make format: format codes with JuliaFormatter"
@echo " - make test: run the tests"
@echo " - make docs: instantiate and build the documentation"
@echo " - make vitepress: start Vitepress site of documentation"
@echo " - make all: run every commands in the above order"

.PHONY: default format test docs all help
.PHONY: default format test docs vitepress all help
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -65,7 +65,7 @@ QuantumToolbox.jl is equipped with a robust set of features:

- **Quantum State and Operator Manipulation:** Easily handle quantum states and operators with a rich set of tools, with the same functionalities as QuTiP.
- **Dynamical Evolution:** Advanced solvers for time evolution of quantum systems, thanks to the powerful [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) package.
- **GPU Computing:** Leverage GPU resources for high-performance computing. For example, you run the master equation directly on the GPU with the same syntax as the CPU case.
- **GPU Computing:** Leverage GPU resources for high-performance computing. Simulate quantum dynamics directly on the GPU with the same syntax as the CPU case.
- **Distributed Computing:** Distribute the computation over multiple nodes (e.g., a cluster). For example, you can run hundreds of quantum trajectories in parallel on a cluster, with, again, the same syntax as the simple case.
- **Easy Extension:** Easily extend the package, taking advantage of the Julia language features, like multiple dispatch and metaprogramming.

Expand Down
4 changes: 4 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
build/
node_modules/
package-lock.json
Manifest.toml
1 change: 1 addition & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
27 changes: 24 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
# How to build documentation locally ?
# How to build documentation and start Vitepress site locally ?

## 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).

## Method 1: Run with `make` command
Run the following command:
Run the following command to instantiate and build the documentation:
```shell
make docs
```

## Method 2: Run `julia` command manually
Run the following command to start Vitepress site of documentation:
> [!NOTE]
> You need to install `Node.js` and `npm` first.
```shell
make vitepress
```

## Method 2: Run commands manually

### Build Pkg
Run the following command:
Expand All @@ -25,3 +32,17 @@ 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
```

Run the following command:
```shell
npm --prefix docs run docs:dev
```
43 changes: 20 additions & 23 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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(;
Expand All @@ -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 = "github.com/qutip/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,
)
15 changes: 15 additions & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
66 changes: 66 additions & 0 deletions docs/src/.vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
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,

// options for @mdit-vue/plugin-toc
// https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
toc: { level: [1, 2] },

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://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>.`
}
}
})
64 changes: 64 additions & 0 deletions docs/src/.vitepress/theme/VersionPicker.vue
Original file line number Diff line number Diff line change
@@ -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>
Loading

0 comments on commit a483e6f

Please sign in to comment.