ci: Deploy documentation to GitHub environment

.github/workflows/build-sola.yml

@@ -32,6 +32,21 @@ jobs:
         find solanet -path solanet/third_party -prune -type f -o -name "*.cpp" -o -name "*.h" >> files.txt
         clang-format --style='file:.clang-format' --dry-run --Werror `cat files.txt`
 
+  # Build documentation to check if build succeeds.
+  # Building for deployment happens in a different workflow.
+  build_documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Install pip dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Install doxygen
+        run: sudo apt-get install -y doxygen
+      - name: Build mkdocs
+        run: mkdocs build
+      - name: Build doxygen
+        run: doxygen
 
   ns-3_compile:
     runs-on: ubuntu-22.04

.github/workflows/documentation.yml

@@ -0,0 +1,57 @@
+# This workflow file is adapted from https://github.com/actions/starter-workflows/blob/f3c5d7931d054ffbbdcbfdc463cc3bd0def74929/pages/mdbook.yml
+# which is licensed under the MIT license.
+
+name: Build and deploy documentation
+
+on:
+  push:
+    branches: ["main"]
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: 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@v3
+      - name: Install pip dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Install doxygen
+        run: sudo apt-get install -y doxygen
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Build mkdocs
+        run: mkdocs build
+      - name: Build doxygen
+        run: |
+          doxygen
+          mv doxygen_output/html html/doxygen
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./html
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/requirements.txt

@@ -0,0 +1,26 @@
+certifi==2023.7.22
+charset-normalizer==3.2.0
+click==8.1.6
+colorama==0.4.6
+ghp-import==2.1.0
+idna==3.4
+Jinja2==3.1.2
+Markdown==3.4.4
+MarkupSafe==2.1.3
+mergedeep==1.3.4
+mkdocs==1.5.1
+mkdocs-material==9.1.21
+mkdocs-material-extensions==1.1.1
+packaging==23.1
+pathspec==0.11.2
+platformdirs==3.10.0
+Pygments==2.15.1
+pymdown-extensions==10.1
+python-dateutil==2.8.2
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.6.3
+requests==2.31.0
+six==1.16.0
+urllib3==2.0.4
+watchdog==3.0.0