Develop

.devcontainer/humble/Dockerfile

@@ -14,6 +14,7 @@ RUN apt-get update && apt-get upgrade -y \
     && apt-get install -y \
     sudo \
     git \
+    doxygen \
     && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
     && chmod 0440 /etc/sudoers.d/$USERNAME
 

.devcontainer/jazzy/Dockerfile

@@ -14,6 +14,7 @@ RUN apt-get update && apt-get upgrade -y \
     && apt-get install -y \
     sudo \
     git \
+    doxygen \
     && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
     && chmod 0440 /etc/sudoers.d/$USERNAME
 

.github/workflows/doxygen-pages.yml

@@ -0,0 +1,86 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - Doxygen
+      - README.md
+      - docs/**
+      - '**/*.md'
+      - '**/*.dox'
+      - '**/*.h'
+      - '**/*.hh'
+      - '**/*.hpp'
+      - '**/*.hxx'
+      - '**/*.c'
+      - '**/*.cc'
+      - '**/*.cpp'
+      - '**/*.cxx'
+      - '**/*.py'
+      - .github/workflows/doxygen-pages.yml
+  pull_request:
+    branches:
+      - main
+    paths:
+      - Doxygen
+      - README.md
+      - docs/**
+      - '**/*.md'
+      - '**/*.dox'
+      - '**/*.h'
+      - '**/*.hh'
+      - '**/*.hpp'
+      - '**/*.hxx'
+      - '**/*.c'
+      - '**/*.cc'
+      - '**/*.cpp'
+      - '**/*.cxx'
+      - '**/*.py'
+      - .github/workflows/doxygen-pages.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen
+
+      - name: Build HTML documentation
+        run: |
+          doxygen Doxygen
+          touch docs/html/.nojekyll
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/html
+
+  deploy-pages:
+    if: github.event_name != 'pull_request' && github.ref_name == github.event.repository.default_branch
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

capabilities2_documentation/Doxygen → Doxygen

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = docs
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -170,7 +170,7 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = .
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -864,7 +864,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../"
+INPUT                  = .
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -952,7 +952,9 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = ./build \
+                         ./install \
+                         ./log
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1005,8 +1007,8 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = "../capabilities2_runner/docs/images" \
-                         "../capabilities2/docs/images"
+IMAGE_PATH             = "capabilities2_runner/docs/images" \
+                         "docs/images"
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1062,7 +1064,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = "../readme.md"
+USE_MDFILE_AS_MAINPAGE = "README.md"
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

readme.md → README.md

@@ -46,6 +46,7 @@ ros2 launch capabilities2_server capabilities2_server.launch.py
 
 - [Motivation and Example Use Cases](./docs/motivation_and_examples.md)
 - [Design Information](./docs/design.md)
+- [Generated API and docs site](./docs/readme.md)
 - [Registering a capability](./capabilities2_server/docs/register.md)
 - [Terminal based capability usage](./capabilities2_server/docs/terminal_usage.md)
 - [Running test scripts](./docs/run_test_scripts.md)

docs/readme.md

@@ -1,13 +1,16 @@
 # Docs
 
-For detailed information about the code, build the code documentation using Doxygen. see [`capabilities2_documentation`](../capabilities2_documentation/).
+The documentation site is generated with Doxygen from the existing Markdown in this `docs/` tree together with comments from the source code. The Doxygen configuration lives at the repository root in [`Doxygen`](../Doxygen).
 
 ```bash
-# in the devcontainer
-cd capabilities2_documentation
-doxygen Doxyfile
+# from the repository root
+doxygen Doxygen
 ```
 
+The generated HTML site is written to `docs/html/` and the entry page is `docs/html/index.html`.
+
+For GitHub Pages, this repository can use GitHub Actions as both the build source and the deployment source. The workflow in `.github/workflows/doxygen-pages.yml` rebuilds the site whenever files change and deploys the generated `docs/html/` artifact to Pages.
+
 ## Basic Tutorial
 
 A basic tutorial can be found in [here](./basic_tutorial.md). This tutorial will guide you through the process of creating a simple capability and running it.