Hosting Documentation

.github/workflows/Documenter.yml

@@ -0,0 +1,50 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Documenter
+
+on:
+ # Runs on pushes targeting the `main` branch.
+ push:
+ branches:
+ - main
+ tags: ['*']
+ pull_request:
+
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+# 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
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Setup Julia
+ uses: julia-actions/setup-julia@v1
+ - name: Pull Julia cache
+ uses: julia-actions/cache@v1
+ - 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 }} # 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

docs/.gitignore

@@ -0,0 +1,4 @@
+build/
+node_modules/
+package-lock.json
+Manifest.toml

docs/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
+
+[compat]
+Documenter = "1.5"
+DocumenterVitepress = "0.1"

docs/make.jl

@@ -0,0 +1,24 @@
+using Documenter, DocumenterVitepress
+
+using Subzero
+
+makedocs(;
+ modules=[Subzero],
+ authors="Skylar Gering",
+ repo="https://github.com/Caltech-OCTO/Subzero.jl",
+ sitename="Subzero.jl",
+ format=DocumenterVitepress.MarkdownVitepress(
+ repo = "https://github.com/Caltech-OCTO/Subzero.jl",
+ devurl = "dev",
+ deploy_url = "Caltech-OCTO.github.io/Subzero.jl",
+ ),
+ pages=[
+ "Home" => "index.md",
+ ],
+ warnonly = true,
+)
+
+deploydocs(;
+ repo="https://github.com/Caltech-OCTO/Subzero.jl",
+ push_preview=true,
+)

docs/package.json

@@ -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"
+ }
+}

docs/src/.vitepress/config.mts

@@ -0,0 +1,48 @@
+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 <a href="https://luxdl.github.io/DocumenterVitepress.jl/dev/" target="_blank"><strong>DocumenterVitepress.jl</strong></a><br>',
+ copyright: `© Copyright ${new Date().getUTCFullYear()}.`
+ }
+ }
+})

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