Standup basic mkdocs documentation site

Signed-off-by: Evan Flynn <[email protected]>

.github/actions/generate-doxybook/action.yml

@@ -0,0 +1,59 @@
+name: Generate doxybook2
+description: Generate markdown using doxybook2 with given configuration
+inputs:
+  input-doxygen-artifact:
+    required: true
+    description: Name of input doxygen artifact to download
+  doxygen-artifact-extraction-path:
+    required: true
+    description: Path to extract input doxygen artifact to
+  doxybook2-version:
+    required: true  # TODO: make this optional
+    description: Version of doxybook2 to download and use
+  output-path:
+    required: true
+    description: The path to generate the doxybook2 markdown to
+  doxybook2-config-path:
+    required: true  # TODO: make this optional with smart default
+    description: Path to the doxybook2 configuration file (including .json extension)
+  base-url:
+    required: true  # TODO: make this optional by adding logic below
+    description: Base URL to overwrite the default with
+  artifact-path:
+    required: true
+    description: Path to directory to upload as artifact
+  artifact-name:
+    required: true
+    description: Name of the artifact to upload
+  artifact-retention-days:
+    required: true
+    description: Number of days to keep the artifact for
+runs:
+  using: composite
+  steps:
+    - name: Download Doxygen XML
+      uses: actions/download-artifact@v3
+      with:
+        name: ${{ inputs.input-doxygen-artifact }}
+        path: ${{ inputs.doxygen-artifact-extraction-path }}
+    - name: Build API Reference
+      shell: bash
+      run: |
+        # ensure output directory exists
+        mkdir -p ${{ inputs.output-path }}
+        export DOXYBOOK_URL=https://github.com/matusnovak/doxybook2/releases/download
+        export DOXYBOOK_URL=${DOXYBOOK_URL}/${{ inputs.doxybook2-version }}
+        export DOXYBOOK_ZIP=doxybook2-linux-amd64-${{ inputs.doxybook2-version }}.zip
+        wget ${DOXYBOOK_URL}/${DOXYBOOK_ZIP}
+        sudo apt-get install unzip
+        unzip ${DOXYBOOK_ZIP}
+        ./bin/doxybook2 --input ${{ inputs.doxygen-artifact-extraction-path }} \
+          --output ${{ inputs.output-path }} \
+          --config ${{ inputs.doxybook2-config-path }} \
+          --config-data '{"baseUrl": "${{ inputs.base-url }}"}'
+    - name: Upload API reference
+      uses: actions/upload-artifact@v3
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ inputs.artifact-path }}
+        retention-days: ${{ inputs.artifact-retention-days }}

.github/actions/generate-doxygen/action.yml

@@ -0,0 +1,32 @@
+name: Generate doxygen documentation and upload as artifact
+description: Build doxygen documentation with given configuration
+inputs:
+  working-directory:
+    required: true
+    description: Working directory to run doxygen from
+  doxyfile-path:
+    required: true
+    description: The path to checkout the given repository too
+  artifact-path:
+    required: true
+    description: Path to directory to upload as artifact
+  artifact-name:
+    required: true
+    description: Name of the artifact to upload
+  artifact-retention-days:
+    required: true
+    description: Number of days to keep the artifact for
+runs:
+  using: composite
+  steps:
+    - name: Run doxygen on source
+      uses: mattnotmitt/doxygen-action@v1
+      with:
+        working-directory: ${{ inputs.working-directory }}
+        doxyfile-path: ${{ inputs.doxyfile-path }}
+    - name: Upload Doxygen XML
+      uses: actions/upload-artifact@v3
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: ${{ inputs.artifact-path }}
+        retention-days: ${{ inputs.artifact-retention-days }}

.github/workflows/docs.yml

@@ -0,0 +1,158 @@
+name: Build Documentation
+
+on:
+  workflow_run:
+    workflows: [Build and Test]
+    types: [completed]
+    branches: [ros2]
+  pull_request:
+    branches:
+      - ros2
+  workflow_dispatch:
+
+env:
+  WORKSPACE_PATH: ros_ws/src/usb_cam
+  DOXYGEN_ARTIFACT: doxygen_xml
+  DOXYBOOK_ARTIFACT: api_reference
+  DOXYBOOK_VERSION: v1.4.0
+
+# only run one build doc workflow at a time, cancel any running ones
+concurrency: 
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  generate-doxygen:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Make sure output directory exists
+        run: mkdir -p ${{ env.WORKSPACE_PATH }}
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          path: ${{ env.WORKSPACE_PATH }}
+      - name: Generate doxygen and upload as artifact
+        # TODO: figure out way to use WORKSPACE_PATH var here
+        uses: ./ros_ws/src/usb_cam/.github/actions/generate-doxygen
+        with:
+          working-directory: ${{ env.WORKSPACE_PATH }}
+          doxyfile-path: 'docs/doxygen.config'
+          artifact-path: ${{ env.WORKSPACE_PATH }}/docs/xml
+          artifact-name: ${{ env.DOXYGEN_ARTIFACT }}
+          artifact-retention-days: 30
+  generate-doxybook2:
+    runs-on: ubuntu-latest
+    needs: generate-doxygen
+    steps:
+      - name: Make sure output directory exists
+        run: mkdir -p ${{ env.WORKSPACE_PATH }}
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          path: ${{ env.WORKSPACE_PATH }}
+      - name: Generate API reference and upload as artifact
+        # TODO: figure out way to use WORKSPACE_PATH var here
+        uses: ./ros_ws/src/usb_cam/.github/actions/generate-doxybook
+        with:
+          input-doxygen-artifact: ${{ env.DOXYGEN_ARTIFACT }}
+          doxygen-artifact-extraction-path: ${{ env.WORKSPACE_PATH }}/docs/xml
+          doxybook2-version: ${{ env.DOXYBOOK_VERSION }}
+          doxybook2-config-path: ${{ env.WORKSPACE_PATH }}/docs/doxybook2_config.json
+          output-path: ${{ env.WORKSPACE_PATH }}/docs/api-reference
+          base-url: /usb_cam/latest/api-reference/
+          artifact-path: ${{ env.WORKSPACE_PATH }}/docs/api-reference
+          artifact-name: ${{ env.DOXYBOOK_ARTIFACT }}
+          artifact-retention-days: 30
+  build-mkdocs:
+    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/ros2'
+    needs: generate-doxybook2
+    steps:
+      - name: Make sure output directory exists
+        run: mkdir -p ${{ env.WORKSPACE_PATH }}
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          path: ${{ env.WORKSPACE_PATH }}
+      - name: Download API Reference
+        uses: actions/download-artifact@v3
+        with:
+          name: ${{ env.DOXYBOOK_ARTIFACT }}
+          path: ${{ env.WORKSPACE_PATH }}/docs/api-reference
+      - name: Build mkdocs site
+        run: |
+          cd ${{ env.WORKSPACE_PATH }}
+          # ensure gh-pages git history is fetched
+          git fetch origin gh-pages --depth=1
+          sudo apt-get update -y
+          # install mkdocs dependencies
+          python3 -m pip install -r docs/requirements.txt
+          cd docs
+          # build site
+          mkdocs build
+      - name: Upload docs site
+        uses: actions/upload-artifact@v3
+        with:
+          name: usb_cam_site
+          path: ${{ env.WORKSPACE_PATH }}/site
+  deploy_docs:
+    runs-on: ubuntu-latest
+    # only run on main ros2 branch after jobs listed in `needs` have finished (successful or not)
+    if: github.ref == 'refs/heads/ros2' && always()
+    needs: [build-mkdocs]
+    steps:
+      - name: Make sure output directory exists
+        run: mkdir -p ${{ env.WORKSPACE_PATH }}
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          path: ${{ env.WORKSPACE_PATH }}
+      - name: Download API reference
+        uses: actions/download-artifact@v3
+        with:
+          name: ${{ env.DOXYBOOK_ARTIFACT }}
+          path: ${{ env.WORKSPACE_PATH }}/docs/api-reference
+      - name: Download Foxy reports
+        continue-on-error: true  # Still publish docs even if reports are not available
+        uses: actions/download-artifact@v3
+        with:
+          name: autoware_benchmark_reports_foxy
+          path: ${{ env.WORKSPACE_PATH }}/docs/reports/foxy
+      - name: Download Galactic reports
+        continue-on-error: true  # Still publish docs even if reports are not available
+        uses: actions/download-artifact@v3
+        with:
+          name: autoware_benchmark_reports_galactic
+          path: ${{ env.WORKSPACE_PATH }}/docs/reports/galactic
+      - name: Download Humble reports
+        continue-on-error: true  # Still publish docs even if reports are not available
+        uses: actions/download-artifact@v3
+        with:
+          name: autoware_benchmark_reports_humble
+          path: ${{ env.WORKSPACE_PATH }}/docs/reports/humble
+      - name: Download Rolling reports
+        continue-on-error: true  # Still publish docs even if reports are not available
+        uses: actions/download-artifact@v3
+        with:
+          name: autoware_benchmark_reports_rolling
+          path: ${{ env.WORKSPACE_PATH }}/docs/reports/rolling
+      - name: Deploy mkdocs site
+        shell: bash
+        run: |
+          cd ${{ env.WORKSPACE_PATH }}
+          # ensure gh-pages git history is fetched
+          git fetch origin gh-pages --depth=1
+          sudo apt-get update -y
+          # install docs dependencies
+          python3 -m pip install -r docs/requirements.txt
+          # TODO: mike rebuilds entire site, instead we should
+          # skip the build and download site artifact from previous workflow
+          if [ -z ${{ github.event.release.tag_name }}]; then
+            export NEW_VERSION=main
+          else
+            export NEW_VERSION=${{ github.event.release.tag_name }}
+          fi
+          git config user.name doc-bot
+          git config user.email doc-bot@usb_cam.com
+          mike deploy --push --update-aliases $NEW_VERSION latest
+

.gitignore

@@ -2,3 +2,8 @@
 .project
 .settings
 **__pycache__
+
+
+# documentation
+docs/xml
+docs/site

docs/.pages

@@ -0,0 +1,4 @@
+nav:
+  - Home: index.md
+  - API Reference: api-reference
+  - ...

docs/doxybook2_config.json

@@ -0,0 +1,44 @@
+{
+  "baseUrl": "/usb_cam/api-reference/",
+  "copyImages": true,
+  "fileExt": "md",
+  "filesFilter": [],
+  "folderClassesName": "Classes",
+  "folderGroupsName": "Modules",
+  "folderNamespacesName": "Namespaces",
+  "foldersToGenerate": [
+    "modules",
+    "classes",
+    "namespaces"
+  ],
+  "formulaBlockEnd": "\\]",
+  "formulaBlockStart": "\\[",
+  "formulaInlineEnd": "\\)",
+  "formulaInlineStart": "\\(",
+  "imagesFolder": "images",
+  "indexClassesName": "index",
+  "indexClassesTitle": "Classes",
+  "indexExamplesName": "index",
+  "indexGroupsName": "index",
+  "indexGroupsTitle": "Modules",
+  "indexInFolders": true,
+  "indexNamespacesName": "index",
+  "indexNamespacesTitle": "Namespaces",
+  "linkAndInlineCodeAsHTML": false,
+  "linkLowercase": false,
+  "linkSuffix": "/",
+  "mainPageInRoot": true,
+  "mainPageName": "index",
+  "sort": true,
+  "templateIndexClasses": "index_classes",
+  "templateIndexGroups": "index_groups",
+  "templateIndexNamespaces": "index_namespaces",
+  "templateKindClass": "kind_class",
+  "templateKindDir": "kind_file",
+  "templateKindGroup": "kind_nonclass",
+  "templateKindInterface": "kind_class",
+  "templateKindNamespace": "kind_nonclass",
+  "templateKindStruct": "kind_class",
+  "templateKindUnion": "kind_class",
+  "useFolders": true
+}