[Rolling] Migrate Nav2 Documentation from Sphinx to MkDocs

.circleci/config.yml

@@ -6,32 +6,51 @@ references:
       path: .
   setup_doc_dependencies: &setup_doc_dependencies
     run:
-      name: Install Doc Dependencies
+      name: Install documentation dependencies
       command: |
         export DEBIAN_FRONTEND=noninteractive
         apt update
         apt install -y \
-          doxygen \
           git \
-          graphviz \
-          make \
-          openjdk-8-jre \
           openssh-server \
           python3-pip \
-          ttf-dejavu
+          python3-venv
+        python3 -m venv /nav2_docs/venv
+        . /nav2_docs/venv/bin/activate
         pip3 install -r requirements.txt
-  make_docs: &make_docs
+  build_docs: &build_docs
     run:
+      name: Build documentation
       command: |
-        make html
-  store_docs: &store_docs
+        . /nav2_docs/venv/bin/activate
+        mkdocs build
+  store_built_docs: &store_built_docs
     store_artifacts:
-        path: _build/html
-        destination: html
+      path: ./site
+      destination: build_site
   publish_docs: &publish_docs
     run:
+      name: Deploy documentation
       command: |
-        make publish
+        # Set up git configuration
+        git config user.name ci
+        git config user.email ci@noreply.com
+
+        . /nav2_docs/venv/bin/activate
+
+        TITLE=${CIRCLE_BRANCH^}
+        mike deploy $CIRCLE_BRANCH --title=$TITLE --push --allow-empty \
+          --message "[skip ci] Deployed $CIRCLE_SHA1 to $CIRCLE_BRANCH"
+
+        # Set default version only once
+        if ! git cat-file -e origin/gh-pages:index.html; then
+          mike set-default rolling --push
+          echo "The default version is set to Rolling"
+        fi
+  store_published_docs: &store_published_docs
+    store_artifacts:
+      path: ./site
+      destination: publish_site
   install_deployment_key: &install_deployment_key
     add_ssh_keys:
       fingerprints:
@@ -42,20 +61,21 @@ commands:
     description: "Install documentation dependencies"
     steps:
       - *setup_doc_dependencies
-  build_docs:
-    description: "Build docs"
+  build_and_store_docs:
+    description: "Build and store docs"
     steps:
-      - *make_docs
-      - *store_docs
-  publish_docs_to_gh_pages_branch:
-    description: "Commit newly built docs to gh-pages branch"
+      - *build_docs
+      - *store_built_docs
+  publish_and_store_docs:
+    description: "Commit newly built docs to gh-pages branch and store the build result"
     steps:
       - *publish_docs
+      - *store_published_docs
 
 executors:
   docs_exec:
     docker:
-      - image: ubuntu:focal
+      - image: ubuntu:noble
     working_directory: /nav2_docs
 
 jobs:
@@ -64,29 +84,30 @@ jobs:
     steps:
       - *on_checkout
       - install_doc_dependencies
-      - build_docs
-      - persist_to_workspace:
-          root: .
-          paths:
-            - _build
+      - build_and_store_docs
   docs_publish:
     executor: docs_exec
     steps:
       - *on_checkout
       - install_doc_dependencies
       - *install_deployment_key
-      - attach_workspace:
-          at: .
-      - publish_docs_to_gh_pages_branch
+      - publish_and_store_docs
 
 workflows:
-  version: 2
-  build_and_publish_docs:
+  build_docs:
+    jobs:
+      - docs_build:
+          filters:
+            branches:
+              ignore:
+                - rolling
+  publish_docs:
     jobs:
-      - docs_build
       - docs_publish:
-          requires:
-            - docs_build
+          # 'serial-group' prevents gh-pages push conflicts when multiple branches deploy simultaneously.
+          # Serial group ensures only one docs_publish job runs at a time across the org.
+          serial-group: << pipeline.project.slug >>/gh-pages-deploy
           filters:
             branches:
-              only: master
+              only:
+                - rolling

.devcontainer/devcontainer.json

@@ -12,7 +12,6 @@
             "extensions": [
                 "eamodio.gitlens",
                 "esbenp.prettier-vscode",
-                "GitHub.copilot",
                 "streetsidesoftware.code-spell-checker"
             ]
         }

.dockerignore

@@ -10,4 +10,4 @@
 .vscode/
 **.Dockerfile
 **Dockerfile
-_build/
+site

.github/mergify.yml

@@ -0,0 +1,37 @@
+merge_queue:
+  queue_controls_comment: false
+
+pull_request_rules:
+  - name: backport to jazzy at reviewers discretion
+    conditions:
+      - base=rolling
+      - "label=backport-jazzy"
+    actions:
+      backport:
+        branches:
+          - jazzy
+
+  - name: backport to lyrical at reviewers discretion
+    conditions:
+      - base=rolling
+      - "label=backport-lyrical"
+    actions:
+      backport:
+        branches:
+          - lyrical
+
+  - name: ask to resolve conflict
+    conditions:
+      - conflict
+      - author!=mergify
+    actions:
+      comment:
+        message: This pull request is in conflict. Could you fix it @{{author}}?
+
+  - name: circleci build failures
+    conditions:
+      - "check-failure=ci/circleci: docs_build"
+    actions:
+      comment:
+        message: |
+          @{{author}}, your PR has failed to build. Please check CI outputs and resolve issues.

.github/workflows/precommit.yaml

@@ -4,7 +4,8 @@ name: pre-commit
 on:
   pull_request:
   push:
-    branches: [main]
+    branches:
+      - rolling
 
 jobs:
   pre-commit:

.gitignore

@@ -1,6 +1,6 @@
-_build
-lib/
-bin/
-pyvenv.cfg
-.DS_Store
-venv/
+venv
+site
+__pycache__
+
+macros/cache/*
+!macros/cache/README.md

.pre-commit-config.yaml

@@ -16,14 +16,14 @@ repos:
   # Spellcheck in comments and docs
   # skipping of *.svg files is not working...
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.2
     hooks:
       - id: codespell
         args: ['--write-changes', '--ignore-words=.codespell_words']
-        exclude: CHANGELOG\.rst|\.(svg|pyc|drawio|dcf|eds)$
+        exclude: \.(svg|pyc|drawio|dcf|eds)$
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: end-of-file-fixer
       - id: mixed-line-ending

.vscode/tasks.json

@@ -4,32 +4,44 @@
     "version": "2.0.0",
     "tasks": [
         {
-            "label": "Build",
-            "icon": {
-                "id": "gear"
-            },
+            "label": "Create venv",
+            "type": "shell",
+            "command": "python3",
+            "args": ["-m", "venv", "venv"],
+            "problemMatcher": []
+        },
+        {
+            "label": "Install dependencies",
+            "type": "shell",
+            "command": "${workspaceFolder}/venv/bin/pip",
+            "args": ["install", "-r", "requirements.txt"],
+            "dependsOn": ["Create venv"],
+            "problemMatcher": []
+        },
+        {
+            "label": "Build Nav2 Docs",
             "type": "shell",
-            "command": "make html",
-            "isBackground": false,
+            "command": "${workspaceFolder}/venv/bin/mkdocs",
+            "args": ["build"],
+            "dependsOn": ["Install dependencies"],
             "problemMatcher": [],
-            "group": {
-                "kind": "build",
-                "isDefault": true
-              }
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            }
         },
         {
-            "label": "Autobuild",
-            "icon": {
-                "id": "debug-start"
-            },
+            "label": "Start Nav2 Docs live preview server",
             "type": "shell",
-            "command": "make autobuild",
-            "isBackground": true,
+            "command": "${workspaceFolder}/venv/bin/mkdocs",
+            "args": ["serve"],
+            "dependsOn": ["Install dependencies"],
             "problemMatcher": [],
-            "group": {
-                "kind": "build",
-                "isDefault": false
-              }
-        }
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            },
+            "isBackground": true
+        },
     ]
 }