Documentation generation

The Doxygen Package

Currently the CPF provides the ref cpfAddDoxygenPackageComponent function to integrate <a href=”http://www.stack.nl/~dimitri/doxygen/download.html”>Doxygen</a> based documentation generation into the CI-pipeline. Adding a doxygen package-component adds a custom target that runs doxygen with all the owned packages as input.

Searching

The search functionality is configured to use the server-side search approach as described <a href=”http://www.stack.nl/~dimitri/doxygen/manual/extsearch.html”>here</a>. To make it work these points must be implemented.

  • The c DoxygenConfig.txt must contain the correct value for the c SEARCHENGINE_URL key. This means that the url of the c doxysearch.cgi file must be known and accessible <b>before</b> generating the documentation. When the url of the documentation web-server changes, this value must be changed too. One can test if the cgi script works by entering c http://feldrechengeraet/cgi-bin/doxysearch.cgi?test. This should return <tt>test succesfull</tt>. The file c search/search.js in the doxygen directory should also contain a correct linkt to the c doxysearch.cgi file.

  • The web-server needs access to the right c doxysearch.cgi file which is provided by Doxygen. The c doxysearch.cgi file must come from the same version of doxygen that is used to generate the html files and the c doxysearch.db search database.

  • The webserver must be configured to use cgi scripts, which is done by providing the serve-cgi-bin.conf file with the docker-image of the webserver. The Dockerfile makes sure the file is copied into the container.

  • The help generation needs to execute the c doxyindexer.exe to create the c doxysearch.db serach-index for the c doxysearch.cgi.

  • The generated files must be copied to the documentation server container with the command

docker cp /var/lib/jenkins/www/html docserver:/var/www

Adding a dependency graph

CMake allows to generate a dependency graph for the package-components in a CI-project. This dependency graph can be integrated into your doxygen documentation. The doxygen target will also create a second transitive reduced version of the dependency graph. The transitive reduced graph does not show direct dependencies when an indirect dependency exists. This resulst in a cleaner graph, which may sometimes be favoured to the complete graph.

These graphs can be added to the documentation by adding the lines

.. graphviz:: CPFDependencies.dot The projects dependency graph
.. graphviz:: CPFDependenciesTransitiveReduced.dot The projects transitive reduced target dependency graph

to one of your doxygen comments.