Doxygen auto-documentation and its deployment on GitHub Pages

To demonstrate the documentation, I will create one file, which will contain the most important and frequently encountered structures that are usually documented.

Documentation

Since it is completely unimportant for documentation how the logic works internally, I will create one header file and document it.

To get started, do:doxygen -g to create a default configuration file. Comes with Doxygen doxywizard, which provides a graphical interface for changing the configuration file, but I will hardly touch on the settings file in this article, so I will not use it.

Let's create a Math class for mathematical operations.

/**
    \brief Класс для математических операций.

    Данный класс предоставляет функционал разных математических операций для шаблоных типов.
*/
class Math {};

By using brief a brief description is announced, and everything that comes below will be a full description.

To generate documentation, call the command doxygen in the code folder. Let's look at the generated documentation:

Let's add a function to the class Summ. For doxygen to extract a function, it must be in the section public or protected.

/**
    \brief Шаблонная функция суммирования двух объектов

    \tparam T - любой тип, для которого определен оператор суммирования 
    и оператор присваивания

    \param [in] a Первый объект, который нужно сложить
    \param [in] b Второй объект, который нужно сложить

    \return Новый объект типа *T*, равный сумме *a* и *b*.
*/
template <class T>
T Summ(const T& a, const T& b);

Using the command tparam information about template types is indicated.

By using param information about the input value is indicated. This command has an additional parameter that specifies the direction of the variable. You can read about it here.

By using return information about the return value is indicated.

Now to the docks:

Let's add one more function. Let this be a root extraction function.

    /**
        \brief Шаблонная функция извлечения корня из объекта

        \tparam T - любой тип, из которого можно извлечь корень

        \param [in] a Объект для извлечения корня

        \return Новый объект типа *T*, равный корню *a*.


        \code{cpp}
        Math m;

        double d = m.Sqrt(2.542);
        \endcode

        \warning Не принимает отрицательные значения
    */
    template <class T>
    T Sqrt(const T& a);

The first part of the function description was discussed in the previous function, so let’s move on to a new one.

Team code needed to place the code in the documentation. This can be convenient, for example, to demonstrate a function call.

By using warning You can mark important information so that it is difficult to miss.

Great, now we have HTML documentation that is created from source code and for this we need to call just one command.

Doxygen Awesome

The docks turned out good, but not very beautiful. You can fix this using styles, for example, this. It's quite beautiful and that's what I usually use.

To install it, download the latest release from GitHub and place it in your project folder. If you don’t want to clutter your project with unnecessary files, you can write a script for automatic cloning of styles and layout of documentation. Since the main thing is the style, I prefer to take only it and store it directly in the project.

To connect a style, you need to add it to the Doxyfile. To do this, you need to assign the parameter “HTML_EXTRA_STYLESHEET” path to the style file.

This can be done through a text editor:

Or through doxywizard:

Let's look at the new style. This is what the class description looks like:

This is the Sqrt method:

Well, the last method:

Great! Now the documentation looks beautiful and modern.

Github Pages

First, let's create a repository on GitHub. Open the main repository tab.

Go to the tab Settings and open the section Pages:

In this section, select Static HTML and press the button Configure.

The task configuration file for the CI/CD pipeline will open. All settings are stored in static.yaml file. Using the pipeline, you can call system commands. Calling all commands is described using steps. The description of the steps begins after the line steps. Path to this line: jobs -> deploy -> steps.

The first two steps look like this by default:

When updating GitHub Pages, things may change, but I don't think it will be difficult to figure out where to write your steps.

Now you need to add steps to install Doxygen. The system is used Ubuntuwhich means packages are installed via apt.

# Install Doxygen
- name: Install Doxygen
  run: sudo apt install doxygen && doxygen --version

- name: Install Graphviz
  run: sudo apt install graphviz

To create documentation on the server, add a step that creates documentation:

# Create documentation   
- name: Create documentation     
  run: doxygen

Documentation is being created, but it needs to be deployed. To do this, you need to specify the path to the folder with index.html in step Upload artifact. By default this step looks like this:

Path to the main page of the site: ./html/index.html. Then this step will look like this:

Commit the new file to the project. Using the tab actions you can track all actions.

For convenience, I will leave the full static.yaml file.

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v4

      # Install Doxygen
      - name: Install Doxygen
        run: sudo apt install doxygen && doxygen --version

      - name: Install Graphviz
        run: sudo apt install graphviz
        
      # Create documentation   
      - name: Create documentation     
        run: doxygen
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: './html/'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Now all that's left to do is add the source code, Doxyfile, and doxygen-awesome.css style to the repository, then commit and push to GitHub.

You can track the deployment of documentation using the icon to the right of the description of the latest commit.

This completes the setup. The link to the documentation is in the section Settings -> Pages.

By clicking on the link you can see the following:

It doesn't look great, but it's easy to fix. Doxygen supports .md files. With their help, you can create full-fledged HTML pages. Let's add it to the project ReadMe.md file and make it the main documentation page, and at the same time make sure that the documentation is updated after the commit.

Now the main page of the project looks like this:

In order for a page to become the main page in the documentation, you need to specify at the beginning of the page \mainpage, however, the same line will be displayed when opening the document, which can be inconvenient, for example, on the main page of a project on GitHub. To solve this problem, you can write a script that will automatically add this line to the beginning of the file when creating documentation, or you can separate the ReadMe.md file from the main documentation page.

Conclusion

So, quite simply, you can set up documentation for the project.