Merge pull request #121 from hmakelin/vitepress2

Add VitePress docs

Author: hmakelin

.dockerignore

@@ -15,8 +15,14 @@ build/
 install/
 log/
 
-# Built Sphinx documentation
-docs/_build/
+# VitePress
+docs/vitepress/docs/.vitepress/dist
+docs/vitepress/docs/.vitepress/build
+docs/vitepress/docs/.vitepress/cache
+docs/vitepress/docs/reference/
+
+# Sphinx
+docs/sphinx/build
 
 # coverage.py files
 .coverage*
@@ -31,3 +37,6 @@ gisnav/test/sitl/ulog_analysis/.ipynb_checkpoints/
 
 # mypy
 .mypy_cache
+
+# node
+node_modules

.github/workflows/build_and_deploy_sphinx_docs.yml renamed to .github/workflows/build_and_deploy_docs.yml

@@ -1,10 +1,14 @@
-name: Build and deploy Sphinx documentation
+name: Build and deploy docs
 
 on:
-  push:
-    # Run when new version tag is pushed
-    tags:
-      - v*
+  # Push trigger is disabled because the Docker container that builds the docs
+  # in this workflow will not have the new tag, meaning the API reference would
+  # have the wrong version tag displayed (commit would still be correct). Need to
+  # build a new Docker image and then use that to build and deploy the docs.
+  #push:
+  #  # Run when new version tag is pushed
+  #  tags:
+  #    - v*
 
   # Allows running manually from the Actions tab
   workflow_dispatch:
@@ -17,11 +21,11 @@ jobs:
       run:
         shell: bash
     steps:
-      - name: Build Sphinx docs
+      - name: Build docs
         run: |
           mkdir -p docs/_build
           docker run ghcr.io/${{ github.repository }}:latest make docs
-          docker cp $(docker ps -q -l):/opt/colcon_ws/src/gisnav/docs/_build docs
+          docker cp $(docker ps -q -l):/opt/colcon_ws/src/gisnav/docs/vitepress/docs/dist docs
 
       - name: Install node
         run: |
@@ -30,19 +34,13 @@ jobs:
           curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
           sudo apt-get install -y nodejs
 
-      - name: Setup pages
+      - name: Configure pages
         uses: actions/configure-pages@v1
 
-      #- name: Make "Upload pages artifact" step work with containers
-      #  run: |
-      #    mkdir -p ${{runner.temp}}
-      #    mkdir -p /__w/_temp
-      #    ln -s ${{runner.temp}}/artifact.tar /__w/_temp/artifact.tar
-
       - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v2
         with:
-          path: 'docs/_build/html/'
+          path: "docs"
 
   deploy:
     needs: build
@@ -58,6 +56,6 @@ jobs:
 
     runs-on: ubuntu-20.04
     steps:
-      - name: Deploy to GitHub Pages
+      - name: Deploy pages
         id: deployment
         uses: actions/deploy-pages@v3

.gitignore

@@ -12,8 +12,14 @@ build/
 install/
 log/
 
-# Built Sphinx documentation
-docs/_build/
+# VitePress
+docs/vitepress/docs/.vitepress/dist
+docs/vitepress/docs/.vitepress/build
+docs/vitepress/docs/.vitepress/cache
+docs/vitepress/docs/reference/
+
+# Sphinx
+docs/sphinx/build
 
 # coverage.py files
 .coverage*
@@ -36,3 +42,6 @@ debian
 
 # mypy
 .mypy_cache
+
+# node
+node_modules

Makefile

@@ -8,5 +8,15 @@ include docker/Makefile
 
 .PHONY: docs
 docs:
-	@$(MAKE) -C docs html
-	@cd docs/_build/html && touch .nojekyll  # for GitHub Pages
+	@cd docs/sphinx && sphinx-build -M markdown ./source ./build
+	@mkdir -p docs/vitepress/docs/reference && cp -r docs/sphinx/build/markdown/* docs/vitepress/docs/reference
+	@cd docs/vitepress && npm run docs:build
+	@cd docs/vitepress/docs/.vitepress/dist && touch .nojekyll  # for GitHub Pages
+
+.PHONY: docs-preview
+docs-preview:
+	@cd docs/vitepress && npm run docs:preview
+
+.PHONY: docs-dev
+docs-preview:
+	@cd docs/vitepress && npm run docs:dev

docker/mavros/Dockerfile

@@ -107,6 +107,12 @@ RUN apt-get update \
     && rm -rf /var/lib/apt/lists/* \
     && apt clean
 
+# Node 18 for building the docs (Sphinx dependencies already in setup.py)
+RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash \
+    && source ~/.nvm/nvm.sh \
+    && nvm install 18 \
+    && nvm use 18
+
 ENTRYPOINT ["/entrypoint.sh"]
 
 # TODO: proper health check - check that public facing topics are publishing

docker/mavros/gisnav/entrypoint.sh

@@ -4,6 +4,9 @@ set -e
 source "/opt/ros/$ROS_VERSION/setup.bash"
 source "/opt/colcon_ws/install/setup.bash" --
 
+# Ensure we have npm to build docs
+source ~/.nvm/nvm.sh
+
 # Needed for pip installed dev tools like pre-commit and sphinx-build
 export PATH=/usr/lib/gisnav:$PATH