(Beta) GitHub Action to Generate and Host your C++ Documentation

This GitHub Action is intended to generate and upload C++ documentation as part of the CI workflow of your project. The goal of this GitHub Action is to enable you to painlessly generate and share documentation with others and keep it in sync with your code by running it with your CI.

Beta Status

This repository is still in beta. We have tested the action with several public projects that already using GitHub Actions for their CI, but due to the complexity inherent in GitHub Actions we are not yet fully confident that it will work in all situations. We hope that you, the user, will try out this service and report back if there are any problems so we can fix them. Please file an issue in this GitHub repository if you encounter any problems.

Usage

Creating a hdoc.io account

To be able to host your documentation publically, you need to create an account on hdoc.io and generate an API key for your project. This is free, and we do not share your personal information.

• Create an account on hdoc.io if you don't already have one.
• Create a project and save the API key that appears during the project creation process.
• Add the API key as an Encrypted secret in the GitHub repository you want to use the GitHub Action on.

Now you're ready to add the GitHub Action to your project!

Enabling the hdoc GitHub Action on your project

hdoc needs a compile_commands.json file to be able to analyze your project. These files are generated by your build system (CMake, meson, etc.) during the configuration step of the build process. You can simply add the hdoc GitHub Action to your existing file if you're already using GitHub Actions to build your project. Let's walk through an example below.

This example assumes you have an existing workflow that install dependencies, configures your project with CMake, and builds the project. Example code is shown below:

name: example-project

# Triggers the workflow on push or pull request events but only for the main branch
on:
  push:
    branches: [ main ]

# A simple workflow to build a C++ project
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies, then configure and build project
        run: |
          sudo apt install build-essential cmake ninja-build
          cmake -GNinja -Bbuild
          ninja -C build

To add hdoc, instruct CMake to generate a compile_commands.json at configure-time and add a step to the workflow that uses the hdoc GitHub Action. The diff below shows the changes needed to the example above.

name: example-project

# Triggers the workflow on push or pull request events but only for the main branch
on:
  push:
    branches: [ main ]

# A simple workflow to build a C++ project and generate documentation with hdoc
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies, then configure and build project
        run: |
          sudo apt install build-essential cmake ninja-build
-         cmake -GNinja -Bbuild
-         ninja -C build
+         cmake -GNinja -Bbuild -DCMAKE_EXPORT_COMPILE_COMMANDS=1
+         ninja -C build  # Optional, you don't need to build the project to use hdoc

+     - name: Run hdoc to generate documentation and push it to docs.hdoc.io
+       uses: hdoc/hdoc-github-action@v2
+       with:
+         compile-commands-path: build/compile_commands.json
+         hdoc-api-key: ${{ secrets.HDOC_PROJECT_API_KEY }}

This GitHub Workflow will accomplish the following:

• Install dependencies.
• Configure your project to be built with CMake and generate a compile_commands.json file.
• (Optionally) build your project.
• hdoc will run over your project, generate documentation, and push it to docs.hdoc.io.