Work on Converting to VitePress

.github/workflows/documentation.yml

@@ -1,27 +1,51 @@
-# https://documenter.juliadocs.org/stable/man/hosting/#GitHub-Actions
-name: Documentation
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Deploy documentation
 
 on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
   push:
     branches:
-      - main
-    tags: '*'
+      -  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
+  actions: 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:
-    permissions:
-      contents: write
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
-        with:
-          version: '1.6'
-      - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
-      - name: Build and deploy
+      - name: Checkout
+        uses: actions/checkout@v4
+        with: # Fetches the last commit only
+          fetch-depth: 0
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@v1
+      - name: Pull Julia cache
+        uses: julia-actions/cache@v1
+      - name: Deploy
+        uses: julia-actions/julia-docdeploy@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          GKSwstype: "100" # https://discourse.julialang.org/t/generation-of-documentation-fails-qt-qpa-xcb-could-not-connect-to-display/60988
+          JULIA_DEBUG: "Documenter"
+          DATADEPS_ALWAYS_ACCEPT: true

.github/workflows/pr_comment.yml

@@ -0,0 +1,14 @@
+name: pr_comment
+on:
+  pull_request:
+    types: [opened, reopened]
+jobs:
+  pr_comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR comment
+        if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name # if this is a pull request build AND the pull request is NOT made from a fork
+        uses: thollander/actions-comment-pull-request@71efef56b184328c7ef1f213577c3a90edaa4aff
+        with:
+          message: 'Once the build has completed, you can preview your PR at this URL: https://biojulia.dev/BiojuliaDocs/previews/PR${{ github.event.number }}/'
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -15,14 +15,26 @@ similar to [SciMLDocs](https://github.com/SciML/SciMLDocs) (see the production p
 
 The rendered BioJuliaDocs site, for testing purposes, is published online using GitHub Pages at [biojulia.dev/BioJuliaDocs](https://biojulia.dev/BioJuliaDocs). A GitHub action rebuilds the site on every successful pull request.
 
-To deploy the site locally:
+To deploy the site locally, open two separate julia processes,
+and activate the "docs/" project.
+Then, in the first, run:
+
 ```julia
 # Make sure you are within or are pointing to the the docs/ folder
-using Documenter, LiveServer
-include("make.jl")
-serve(dir="build")
+using LiveServer
+servedocs(; foldername=pwd())
 ```
 
+And in the other, run:
+
+```julia
+using DocumenterVitepress
+
+DocumenterVitepress.dev_docs("build"; md_output_path="")
+```
+
+Open the LocalHost Url spawned by the vitepress process
+
 ## Contributing
 
 We appreciate contributions from users/members of the BioJulia commmunity

docs/.gitignore

@@ -1,3 +1,5 @@
 build/
 site/
 Manifest.toml
+node_modules/
+package-lock.json

docs/Project.toml

@@ -5,6 +5,7 @@ BioSequences = "7e6ae17a-c86d-528c-b3b9-7f778a29fe59"
 BioSymbols = "3c28c6f8-a34d-59c4-9654-267d177fcfa9"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 FASTX = "c2308a5c-f048-11e8-3e8a-31650f418d12"
 FormatSpecimens = "3372ea36-2a1a-11e9-3eb7-996970b6ffbd"
 GFF3 = "af1dc308-cb6b-11e8-32f0-31192efa90f6"

docs/make.jl

@@ -1,39 +1,45 @@
 using Documenter
+using DocumenterVitepress
 
 makedocs(
-    sitename = "Overview of BioJulia",
+    sitename = "BioJulia Unified Docs",
     authors = "Michael Persico",
     modules = Module[],
-    clean = true,
+    clean = false,
     doctest = false,
     draft = false,
     # TODO expand (https://github.com/SciML/SciMLDocs/blob/0fa5c9c43cf768588124861e76c7854e671ad9d7/docs/make.jl#L29C1-L29C63)
-    format = Documenter.HTML(assets=["assets/favicon.ico"]),
+    format = DocumenterVitepress.MarkdownVitepress(
+        repo = "https://github.com/BioJulia/BioJuliaDocs",
+        md_output_path = ".",
+        build_vitepress = false
+    ),
     pages = [
-        "BioJulia: Fast, open, easy software for biology" => "index.md",
         "Getting Started" => [
-            "New User Tutorials" => [
-                "getting_started/juliainstallation.md",
-                "getting_started/toolsinstallation.md",
-                "getting_started/biojuliainstallation.md",
-                "getting_started/casescenarios.md",
-            ],
-            "Comparison With Other Packages/Ecosystems" => [
-                "comparisons/biopython.md",
-                "comparisons/scikitbio.md",
-                "comparisons/bioconductor.md",
-                "comparisons/biojava.md",
-                "comparisons/bioperl.md",
-                "comparisons/bioruby.md",
-            ],
+            "getting_started/juliainstallation.md",
+            "getting_started/toolsinstallation.md",
+            "getting_started/biojuliainstallation.md",
+            "getting_started/casescenarios.md",
+        ],
+        "Comparison With Other Packages/Ecosystems" => [
+            "comparisons/biopython.md",
+            "comparisons/scikitbio.md",
+            "comparisons/bioconductor.md",
+            "comparisons/biojava.md",
+            "comparisons/bioperl.md",
+            "comparisons/bioruby.md",
         ],
         # Showcase of Cool Examples
-        "What is BioJulia?" => ["overview.md",
+        "What is BioJulia?" => [
+            "overview.md",
         ]
     ]
 )
 
 deploydocs(
     repo = "https://github.com/BioJulia/BioJuliaDocs.git",
+    target = "build",
+    devbranch = "main",
+    branch = "gh-pages",
     push_preview = true,
 )

docs/package.json

@@ -0,0 +1,16 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev build/.documenter",
+    "docs:build": "vitepress build build/.documenter",
+    "docs:preview": "vitepress preview build/.documenter"
+  },
+  "dependencies": {
+    "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.12.1",
+    "@shikijs/transformers": "^2.0.3",
+    "markdown-it": "^14.1.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-mathjax3": "^4.3.2",
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-tabs": "^0.5.0"
+  }
+}