Skip to content

Doxygen

Last update: 05. March 2023 (Created: 19. February 2023)

tags: - Doxygen - C - C++ - Documentation

Doxygen

Doxygen can be used to generate documentation from source code.

On Windows the Doxywizard can be used to edit the Doxyfile in a visual interface. The best way to generate a new Doxyfile is to open Doxywizard and configure the parameters in there, and then save it to disk. This file can also be loaded again later. (Note: After editing the file by hand you have to "reopen" it in Doxywizard for the changes to take effect.)

To make Doxygen not look "old-fashioned" you can use Doxygen Awesome: https://jothepro.github.io/doxygen-awesome-css/

Doxygen Template for Doxygen Awesome: KnowledgeBase/DoxygenTemplate/

In order for Doxygen to generate good documentation the code must be commented in a specific way (see: https://doxygen.nl/manual/docblocks.html). For C++ for example the Javadoc style can be used (see: https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html).

Doxygen can also be build inside of Jenkins in you build pipeline. For this Doxygen has to be installed on the node and the HTML Publisher Plugin should be installed on the Jenkins: https://plugins.jenkins.io/htmlpublisher/ In your pipeline you can then add a stage to build the documentation.

// This assumes that the Doxyfile is in the root workspace directory.
stage('Generate Doxygen Documentation')
{
    sh('doxygen Doxyfile')
    publishHTML([allowMissing: false, alwaysLinkToLastBuild: false, keepAll: false, reportDir: 'html/', reportFiles: 'index.html', reportName: 'Doxygen-Documentation', reportTitles: '', useWrapperFileDirectly: true])
}

The documentation will then be "hosted" on the Jenkins and can be accessed in the sidebar of the job (named after reportName in the publishHTML function). If the documentation does not look correct, then check your Doxygen version (when using Doxygen Awesome). It is also possible that the CSP policy is not set in a way that e.g. allows javascript. To fix this you can go to <jenkins-url>/script and paste the following into the console: System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "default-src * 'unsafe-inline' 'unsafe-eval';")

Only do this if you know of the consequences of this action! If the server is accessible from outside the local network this could pose a serious security risk!