Improve JSDoc and Doxygen documentation

.github/workflows/jsdoc-doxygen.yml

@@ -0,0 +1,84 @@
+name: Deploy Doxygen PDF and Update Docs
+on:
+  push:
+    branches: ["master"]
+
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: "docs"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 21
+
+      - name: Install JSDoc
+        run: npm install -g jsdoc
+
+      - name: Generate JSDoc
+        run: jsdoc -c jsdoc.json
+
+      - name: Copy JSDoc to output folder
+        run: |
+          mkdir jsdoc
+          cp -r ./docs/ jsdoc/
+
+      - name: Upload JSDoc
+        uses: actions/upload-artifact@v4
+        with:
+          name: JSDoc
+          path: jsdoc/
+
+      - name: Install Doxygen
+        run: sudo apt-get install -y doxygen
+
+      - name: Install Graphviz
+        run: sudo apt-get install -y graphviz
+
+      - name: Run Doxygen
+        run: doxygen Doxyfile
+
+      - name: Generate PDF using LaTeX Action
+        uses: xu-cheng/latex-action@v2
+        with:
+          working_directory: docs/latex/
+          root_file: refman.tex
+
+      - name: Copy PDF to more visible location in docs and output folder
+        run: |
+          mkdir doxygen
+          cp ./docs/latex/refman.pdf ./docs/hivtrace-viz-doxygen-docs.pdf
+          cp ./docs/latex/refman.pdf ./doxygen/hivtrace-viz-doxygen-docs.pdf
+
+      - name: Upload Doxygen Docs PDF
+        uses: actions/upload-artifact@v4
+        with:
+          name: Doxygen-PDF
+          path: doxygen/hivtrace-viz-doxygen-docs.pdf
+
+      - name: Push updated docs to master
+        run: |
+          git config --global user.name 'GitHub Actions'
+          git config --global user.email '[email protected]'
+          git add docs/
+
+          # Check for changes
+          if git diff-index --quiet HEAD --; then
+            # No changes
+            echo "No changes to commit"
+          else
+            # Changes detected
+            git commit -m "Update JSDoc and Doxygen PDF"
+            git push origin master
+          fi

README.md

@@ -22,3 +22,12 @@ Navigate your browser to localhost:8273
 The HIV-Trace webpage was formerly hosted using github-pages at https://veg.github.io/hivtrace-viz/ but has been migrated to using a pm2 process at hivtrace-viz.hyphy.org (see veg/operations documentation for details).
 
 The master branch of this repo should always be in sync with what is published to NPM and is live on the production website. With the exception of urgent bug fixes, all changes to veg/master should be done via pull requests from veg/develop.
+
+
+## Documentation
+
+A basic JSDoc documentation of hivtrace-viz can be found at `docs/` and can be viewed by cloning the repository and opening `docs/index.html` in a browser (or running a basic web server in the `docs/` directory, e.g. `python -m http.server`).
+
+A PDF version of the documentation can be found at `docs/hivtrace-viz-doxygen-docs.pdf`.
+
+This documentation is generated automatically using `jsdoc -c jsdoc.json` and ran automatically as part of the CI/CD pipeline (see `.github/workflows/jsdoc-doxygen.yml`).