Automatically publish documentation of your code using Github Actions and Doxygen

2 min readApr 11, 2020

Good documentation is essential for any project. This post will help you get started in setting up your documentation within minutes. If you already have doxygen configured, jump to Setting up automatic deployment section.

I picked Doxygen as it is cross platform and supports all major languages. It is pretty easy to use and works out of the box.

All code can be found in this repository.

1. Installation of Doxygen

The following commands can be used to install Doxygen. More details can be found here.

Installation on MacOS

brew install doxygen

Installation on Ubuntu

sudo apt-get install -y doxygen

2. Setting up Doxygen Configuration

Create the default configuration file using the following command

doxygen -g

3. Configure Doxyfile

Set RECURSIVE to YES
Set EXCLUDE and EXCLUDE_PATTERNS to exclude directories you don’t want documented. Typically library code and plugins come here.
Set PROJECT_NAME to the name of your project

Thats it for now!

4. Document your Code

Document your code according the Doxygen guidelines. To get started, checkout the examples in the src directory in this repo. It is important to document your code in a detailed manner using the annotations supported by Doxygen.

5. Test your documentation locally

Run doxygen to generate documentation to see output documentation locally

By default, web documentation and pdf documentation files are generated in html and latex directories respectively.
View the web documentation at html/index.html
Compile pdf documentation by running make in thelatex directory

6. Setup automatic publishing of documentation

This is the fun part! You can automatically deploy your documentation using github actions. Every commit to master will trigger the action and the documentation will get updated. Download main.yml file from this repository.

Copy the action file main.yml to .github/workflows/main.yml in your repository
Commit and Push to github
Github action should automatically start running
Confirm that github is set to deploy gh-pages branch in settings page

Thats it! your documentation should automatically be deployed and can be accessed from http://<your-github-username>.github.io/<your-repo-name>/index.html

Let me know what you think of this approach in the comments!