diff --git a/.devcontainer/humble/Dockerfile b/.devcontainer/humble/Dockerfile index a71f968..2c5b6b4 100644 --- a/.devcontainer/humble/Dockerfile +++ b/.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 diff --git a/.devcontainer/jazzy/Dockerfile b/.devcontainer/jazzy/Dockerfile index 97163cc..72a2198 100644 --- a/.devcontainer/jazzy/Dockerfile +++ b/.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 diff --git a/.github/workflows/doxygen-pages.yml b/.github/workflows/doxygen-pages.yml new file mode 100644 index 0000000..32f0222 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/capabilities2_documentation/Doxygen b/Doxygen similarity index 99% rename from capabilities2_documentation/Doxygen rename to Doxygen index 37e4c5c..1243e04 100644 --- a/capabilities2_documentation/Doxygen +++ b/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 diff --git a/readme.md b/README.md similarity index 98% rename from readme.md rename to README.md index 5deb614..742459c 100644 --- a/readme.md +++ b/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) diff --git a/docs/readme.md b/docs/readme.md index fecd977..11c1b2b 100644 --- a/docs/readme.md +++ b/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.