Improve Documentation (#291)

* Move favicon and logo to where `DocumenterVitepress` expects them

* modify nav-bar and add `VersionPicker`

* modify documentation

Author: ytdHuang

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

@@ -10,12 +10,15 @@ DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recu
 
 const DRAFT = false # set `true` to disable cell evaluation
 
-bib = CitationBibliography(joinpath(@__DIR__, "src", "bibliography.bib"), style=:authoryear)
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "resources", "bibliography.bib"), 
+    style=:authoryear,
+)
 
 const PAGES = [
     "Home" => "index.md",
     "Getting Started" => [
-        "Introduction" => "getting_started.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",
@@ -51,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(;

docs/src/.vitepress/config.mts

@@ -3,6 +3,18 @@ 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!
@@ -35,7 +47,7 @@ export default defineConfig({
                 detailedView: true
             }
         },
-        nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+        nav,
         sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
         editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
         socialLinks: [

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

@@ -2,6 +2,7 @@
 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'
@@ -14,6 +15,7 @@ export default {
         })
     },
     enhanceApp({ app, router, siteData }) {
-        enhanceAppWithTabs(app)
+        enhanceAppWithTabs(app);
+        app.component('VersionPicker', VersionPicker);
     }
 } satisfies Theme

docs/src/.vitepress/theme/style.css

@@ -95,10 +95,13 @@ code {
             #9558B2 30%,
             #CB3C33);
 
+    --vp-home-hero-image-background-image: none; /* remove the blur background */
+    /* (default setting)
     --vp-home-hero-image-background-image: linear-gradient(-45deg,
             #9558B2 30%,
             #389826 30%,
             #CB3C33);
+    */
     --vp-home-hero-image-filter: blur(40px);
 }
 

docs/src/getting_started.md

@@ -2,29 +2,6 @@
 CurrentModule = QuantumToolbox
 ```
 
-## [Installation](@id doc:Installation)
-
-!!! note "Requirements"
-    `QuantumToolbox.jl` requires `Julia 1.10+`.
-
-To install `QuantumToolbox.jl`, run the following commands inside Julia's interactive session (also known as REPL):
-```julia
-using Pkg
-Pkg.add("QuantumToolbox")
-```
-Alternatively, this can also be done in Julia's [Pkg REPL](https://julialang.github.io/Pkg.jl/v1/getting-started/) by pressing the key `]` in the REPL to use the package mode, and then type the following command:
-```julia-REPL
-(1.10) pkg> add QuantumToolbox
-```
-More information about `Julia`'s package manager can be found at [`Pkg.jl`](https://julialang.github.io/Pkg.jl/v1/).
-
-To load the package and check the version information, use either [`QuantumToolbox.versioninfo()`](@ref) or [`QuantumToolbox.about()`](@ref), namely
-```julia
-using QuantumToolbox
-QuantumToolbox.versioninfo()
-QuantumToolbox.about()
-```
-
 ## Brief Example
 
 We now provide a brief example to demonstrate the similarity between [QuantumToolbox.jl](https://github.com/qutip/QuantumToolbox.jl) and [QuTiP](https://github.com/qutip/qutip).

docs/src/index.md

@@ -13,6 +13,9 @@ hero:
     - theme: brand
       text: Getting Started
       link: /getting_started
+    - theme: alt
+      text: Users Guide
+      link: /users_guide/QuantumObject/QuantumObject
     - theme: alt
       text: View on Github
       link: https://github.com/qutip/QuantumToolbox.jl
@@ -37,6 +40,31 @@ features:
 ---
 ```
 
+# [Introduction](@id doc:Introduction)
+
 [QuantumToolbox.jl](https://github.com/qutip/QuantumToolbox.jl) is a cutting-edge Julia package designed for quantum physics simulations, closely emulating the popular Python [QuTiP](https://github.com/qutip/qutip) package. It uniquely combines the simplicity and power of Julia with advanced features like GPU acceleration and distributed computing, making simulation of quantum systems more accessible and efficient. Taking advantage of the Julia language features (like multiple dispatch and metaprogramming), QuantumToolbox.jl is designed to be easily extendable, allowing users to build upon the existing functionalities.
 
 *__With this package, moving from Python to Julia for quantum physics simulations has never been easier__*, due to the similar syntax and functionalities.
+
+# [Installation](@id doc:Installation)
+
+!!! note "Requirements"
+    `QuantumToolbox.jl` requires `Julia 1.10+`.
+
+To install `QuantumToolbox.jl`, run the following commands inside Julia's interactive session (also known as REPL):
+```julia
+using Pkg
+Pkg.add("QuantumToolbox")
+```
+Alternatively, this can also be done in Julia's [Pkg REPL](https://julialang.github.io/Pkg.jl/v1/getting-started/) by pressing the key `]` in the REPL to use the package mode, and then type the following command:
+```julia-REPL
+(1.10) pkg> add QuantumToolbox
+```
+More information about `Julia`'s package manager can be found at [`Pkg.jl`](https://julialang.github.io/Pkg.jl/v1/).
+
+To load the package and check the version information, use either [`QuantumToolbox.versioninfo()`](@ref) or [`QuantumToolbox.about()`](@ref), namely
+```julia
+using QuantumToolbox
+QuantumToolbox.versioninfo()
+QuantumToolbox.about()
+```