docs: API list

docs/make.jl

@@ -24,9 +24,11 @@ ENV["GKSwstype"] = "100"
 
 include("make_md_examples.jl")
 
+include("pages.jl")
+
 makedocs(;
     sitename="HarmonicBalance.jl",
-    authors="Quest",
+    authors="Quest group",
     modules=[
         HarmonicBalance,
         Base.get_extension(HarmonicBalance, :TimeEvolution),
@@ -38,6 +40,7 @@ makedocs(;
         devbranch="master",
         devurl="dev",
     ),
+    pages=pages,
     source="src",
     build="build",
     draft=false,

docs/pages.jl

@@ -1,26 +1,36 @@
 #! format: off
 pages = [
-		"Background" => Any[
-			"background/harmonic_balance.md"
-			"background/stability_response.md"
-			"background/limit_cycles.md"
-		],
-		"Examples" => Any[
-			"examples/simple_Duffing.md"
-			"examples/linear_response.md"
-			"examples/time_dependent.md"
-			"examples/parametron.md"
-			"examples/limit_cycles.md"
-			],
-		"Manual" => Any[
-			"manual/entering_eom.md"
-			"manual/extracting_harmonics.md"
-			"manual/solving_harmonics.md"
-            "manual/Krylov-Bogoliubov_method.md"
-			"manual/plotting.md"
-			"manual/time_dependent.md"
-			"manual/linear_response.md"
-			"manual/saving.md"
-		]
-	]
-#! format: on
+    "Home" => "index.md",
+    "Getting Started" => "introduction/index.md",
+    "Theoretical Background" => [
+        "Floquet expansions" => "background/harmonic_balance.md",
+        "Stability and Linear Response" => "background/stability_response.md",
+        "Limit Cycles" => "background/limit_cycles.md",
+    ],
+    "Tutorials" => [
+        "Steady States" => "tutorials/steady_states.md",
+        "Classifying Solutions" => "tutorials/classification.md",
+        "Linear Response" => "tutorials/linear_response.md",
+        "Transient Dynamics" => "tutorials/time_dependent.md",
+        "Limit Cycles" => "tutorials/limit_cycles.md",
+        "Examples" => [
+        "Wave Mixing" => "examples/wave_mixing.md"
+        "Parametric Three Wave Mixing" => "examples/parametric_via_three_wave_mixing.md"
+        "Parametric Oscillator" => "examples/parametron.md"
+        ],
+    ],
+    "Resources" => [
+        "API" => "manual/API.md",
+        "Bibliography" => "introduction/citation.md",
+        "Manual" => [
+        "Entering Equations of Motion" => "manual/entering_eom.md",
+        "Computing Effective System" => "manual/extracting_harmonics.md",
+        "Computing Steady States" => "manual/methods.md",
+        "Krylov-Bogoliubov" => "manual/Krylov-Bogoliubov_method.md",
+        "Time Evolution" => "manual/time_dependent.md",
+        "Linear Response" => "manual/linear_response.md",
+        "Plotting" => "manual/plotting.md",
+        "Saving and Loading" => "manual/saving.md",
+        ]
+    ],
+]

docs/src/.vitepress/config.mts

@@ -4,16 +4,57 @@ import mathjax3 from "markdown-it-mathjax3";
 import footnote from "markdown-it-footnote";
 import { transformerMetaWordHighlight } from '@shikijs/transformers';
 
+const baseTemp = {
+  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+}
+
+const navTemp = {
+  nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+}
+
+const nav = [
+  ...navTemp.nav,
+  {
+    component: 'VersionPicker'
+  }
+]
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+  base: baseTemp.base,
   title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
   description: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
   cleanUrls: true,
   outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
+  head: [
+    [
+      "script",
+      { async: "", src: "https://www.googletagmanager.com/gtag/js?id=G-RE962QZ6DQ" },
+    ],
+    [
+      "script",
+      {},
+      `window.dataLayer = window.dataLayer || [];
+              function gtag(){dataLayer.push(arguments);}
+              gtag('js', new Date());
+              gtag('config', 'G-RE962QZ6DQ');`,
+    ],
+    ['link', { rel: 'icon', href: '/HarmonicBalance.jl/dev/favicon.ico' }],
+    ['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }],
+    ['link', { rel: 'manifest', href: '/site.webmanifest' }],
+
+    ['script', { src: `/HarmonicBalance.jl/versions.js` }],
+    ['script', { src: `${baseTemp.base}siteinfo.js` }]
+  ],
+  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: [2, 3, 4] }, // for API page, triggered by: [[toc]]
+
     config(md) {
       md.use(tabsMarkdownPlugin),
         md.use(mathjax3),
@@ -22,99 +63,20 @@ export default defineConfig({
     theme: {
       light: "github-light",
       dark: "github-dark"
-    },
-    codeTransformers: [transformerMetaWordHighlight(),],
+    }
   },
-
-  head: [
-      [
-        "script",
-        { async: "", src: "https://www.googletagmanager.com/gtag/js?id=G-RE962QZ6DQ" },
-      ],
-      [
-        "script",
-        {},
-        `window.dataLayer = window.dataLayer || [];
-            function gtag(){dataLayer.push(arguments);}
-            gtag('js', new Date());
-            gtag('config', 'G-RE962QZ6DQ');`,
-      ],
-    ['link', { rel: 'icon', href: '/HarmonicBalance.jl/dev/favicon.ico' }],
-    ['link', { rel: 'manifest', href: '/site.webmanifest' }],
-  ],
-
   themeConfig: {
     outline: 'deep',
-    // https://vitepress.dev/reference/default-theme-config
     logo: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
     search: {
       provider: 'local',
       options: {
         detailedView: true
       }
     },
-
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Getting Started', link: '/introduction' },
-      { text: 'Background', link: '/background/harmonic_balance' },
-      { text: 'Tutorials', link: '/tutorials' },
-      { text: 'Examples', link: '/examples' },
-      {
-        text: 'Manual', items: [
-          { text: 'Entering equations of motion', link: '/manual/entering_eom.md' },
-          { text: 'Computing effective system', link: '/manual/extracting_harmonics' },
-          { text: 'Computing steady states', link: '/manual/methods' },
-          { text: 'Krylov-Bogoliubov', link: '/manual/Krylov-Bogoliubov_method' },
-          { text: 'Time evolution', link: '/manual/time_dependent' },
-          { text: 'Linear response', link: '/manual/linear_response' },
-          { text: 'Plotting', link: '/manual/plotting' },
-          { text: `Saving and loading`, link: '/manual/saving' },
-        ]
-      },
-    ],
-
-    sidebar: {
-      "/introduction/": [
-        { text: 'Introduction', link: '/index' },
-        // { text: 'Overview', link: '/introduction/overview' },
-        // { text: 'Tutorials', link: '/tutorials/index' },
-        { text: 'Citation', link: '/introduction/citation' }
-      ],
-      "/background/": [
-        { text: 'The method of Harmonic Balance', link: '/background/harmonic_balance.md' },
-        { text: 'Stability and linear response', link: 'background/stability_response.md' },
-        { text: 'Limit cycles', link: 'background/limit_cycles.md' }
-      ],
-      "/tutorials/": [
-        { text: 'Steady states', link: '/tutorials/steady_states' },
-        { text: 'Classifying solutions', link: '/tutorials/classification' },
-        { text: 'Linear response', link: '/tutorials/linear_response' },
-        { text: 'Transient dynamics', link: '/tutorials/time_dependent' },
-        { text: 'Limit cycles', link: '/tutorials/limit_cycles' }
-      ],
-      "/examples/": [
-        { text: 'Wave mixing', link: '/examples/wave_mixing' },
-        { text: 'Parametric three wave mixing', link: '/examples/parametric_via_three_wave_mixing' },
-        { text: 'Parametric oscillator', link: '/examples/parametron' }
-      ],
-      "/manual/": [
-        { text: 'Entering equations of motion', link: '/manual/entering_eom.md' },
-        { text: 'Computing effective system', link: '/manual/extracting_harmonics' },
-        { text: 'Computing steady states', link: '/manual/methods' },
-        { text: 'Krylov-Bogoliubov', link: '/manual/Krylov-Bogoliubov_method' },
-        { text: 'Time evolution', link: '/manual/time_dependent' },
-        { text: 'Linear response', link: '/manual/linear_response' },
-        { text: 'Plotting', link: '/manual/plotting' },
-        { text: `Saving and loading`, link: '/manual/saving' }
-      ],
-      "/api/": []
-    },
-
-    editLink: {
-      pattern: 'https://github.com/NonlinearOscillations/HarmonicBalance.jl/edit/main/docs/src/:path',
-      text: 'Edit this page on GitHub'
-    },
+    nav,
+    sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
     socialLinks: [
       { icon: 'github', link: 'https://github.com/NonlinearOscillations/HarmonicBalance.jl' },
       { icon: 'twitter', link: 'https://x.com/Zilberberg_Phys' },
@@ -125,4 +87,4 @@ export default defineConfig({
       copyright: `© Copyright ${new Date().getUTCFullYear()}. Released under the MIT License.`
     },
   }
-})
+})

docs/src/.vitepress/theme/VersionPicker.vue

@@ -0,0 +1,142 @@
+<!-- Adapted from https://github.com/MakieOrg/Makie.jl/blob/master/docs/src/.vitepress/theme/VersionPicker.vue -->
+
+<script setup lang="ts">
+import { ref, onMounted, computed } from 'vue'
+import { useData } from 'vitepress'
+import VPNavBarMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavBarMenuGroup.vue'
+import VPNavScreenMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavScreenMenuGroup.vue'
+
+// Extend the global Window interface to include DOC_VERSIONS and DOCUMENTER_CURRENT_VERSION
+declare global {
+  interface Window {
+    DOC_VERSIONS?: string[];
+    DOCUMENTER_CURRENT_VERSION?: string;
+  }
+}
+
+const props = defineProps<{
+  screenMenu?: boolean
+}>()
+
+const versions = ref<Array<{ text: string, link: string }>>([]);
+const currentVersion = ref('Versions');
+const isClient = ref(false);
+const { site } = useData()
+
+const isLocalBuild = () => {
+  return typeof window !== 'undefined' && (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1');
+}
+
+const getBaseRepository = () => {
+  if (typeof window === 'undefined') return ''; // Handle server-side rendering (SSR)
+  const { origin, pathname } = window.location;
+  // Check if it's a GitHub Pages (or similar) setup
+  if (origin.includes('github.io')) {
+    // Extract the first part of the path as the repository name
+    const pathParts = pathname.split('/').filter(Boolean);
+    const baseRepo = pathParts.length > 0 ? `/${pathParts[0]}` : '';
+    return `${origin}${baseRepo}`;
+  } else {
+    // For custom domains, use just the origin (e.g., https://docs.makie.org)
+    return origin;
+  }
+};
+
+const waitForScriptsToLoad = () => {
+  return new Promise<boolean>((resolve) => {
+    if (isLocalBuild()) {
+      resolve(false);
+      return;
+    }
+    const checkInterval = setInterval(() => {
+      if (window.DOC_VERSIONS && window.DOCUMENTER_CURRENT_VERSION) {
+        clearInterval(checkInterval);
+        resolve(true);
+      }
+    }, 100);
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      clearInterval(checkInterval);
+      resolve(false);
+    }, 5000);
+  });
+};
+
+const loadVersions = async () => {
+  if (typeof window === 'undefined') return; // Guard for SSR
+
+  try {
+    if (isLocalBuild()) {
+      // Handle the local build scenario directly
+      const fallbackVersions = ['dev'];
+      versions.value = fallbackVersions.map(v => ({
+        text: v,
+        link: '/'
+      }));
+      currentVersion.value = 'dev';
+    } else {
+      // For non-local builds, wait for scripts to load
+      const scriptsLoaded = await waitForScriptsToLoad();
+      const getBaseRepositoryPath = computed(() => {
+        return getBaseRepository();
+      });
+
+      if (scriptsLoaded && window.DOC_VERSIONS && window.DOCUMENTER_CURRENT_VERSION) {
+        versions.value = window.DOC_VERSIONS.map((v: string) => ({
+          text: v,
+          link: `${getBaseRepositoryPath.value}/${v}/`
+        }));
+        currentVersion.value = window.DOCUMENTER_CURRENT_VERSION;
+      } else {
+        // Fallback logic if scripts fail to load or are not available
+        const fallbackVersions = ['dev'];
+        versions.value = fallbackVersions.map(v => ({
+          text: v,
+          link: `${getBaseRepositoryPath.value}/${v}/`
+        }));
+        currentVersion.value = 'dev';
+      }
+    }
+  } catch (error) {
+    console.warn('Error loading versions:', error);
+    // Use fallback logic in case of an error
+    const fallbackVersions = ['dev'];
+    const getBaseRepositoryPath = computed(() => {
+        return getBaseRepository();
+      });
+    versions.value = fallbackVersions.map(v => ({
+      text: v,
+      link: `${getBaseRepositoryPath.value}/${v}/`
+    }));
+    currentVersion.value = 'dev';
+  }
+  isClient.value = true;
+};
+
+onMounted(loadVersions);
+</script>
+
+<template>
+  <template v-if="isClient">
+    <VPNavBarMenuGroup
+      v-if="!screenMenu && versions.length > 0"
+      :item="{ text: currentVersion, items: versions }"
+      class="VPVersionPicker"
+    />
+    <VPNavScreenMenuGroup
+      v-else-if="screenMenu && versions.length > 0"
+      :text="currentVersion"
+      :items="versions"
+      class="VPVersionPicker"
+    />
+  </template>
+</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>