Including Doxygen document generation in the built process with Qt Creator

[artwaw]

Good morning,
I've been advised to post my solution to the above here.

Why Doxygen? I like graphs. Mapped function calls, internal dependencies and all that stuff. Integrated with Graphviz and dot, it can create really detailed and well structured reference manuals - and my goal is to leave any tool in the state where it can be built by anyone who knows Qt.

Added bonus is, that upon the build process I receive notifications in Qt Creator about wrongly or not documented parts of the code!

And finally, please excuse me if you are familiar with the operating system, I wish this document to be of use also for developers who don't know a thing about shell or system setup. They just do code.

Use case:

In my company the custom is that hi level documentation is put into Confluence, low level in the git repo together with source code, in easily distinguishable folder, like /techdoc/, /refman/ or something.
That seems to work fine with most of us but overall majority are PHP/JS developers - with me as a single one writing internal tools for desktop users where something can't be run in the browser (or browser interface is not favourable). And so, I found the existing solutions not preferable, since my code is differently structured to begin with.
I am used to Doxygen but Confluence is a pain in its own right when it comes to including external documents. So, I've come to idea that since Doxygen can create LaTeX format, PDF would be simple enough to include.

Prerequisities:

• Doxygen
  You need to have your doxyfile created. If you are not familiar with the file format, just install, configure via Doxywizard and save the file. My, apart from LaTeX, creates QDoc help that I use internally in my Qt environment. More details on that variant here (external link to SO) - link provided by @json_7 in other thread. This way Doxygen can build documentation in many formats with single run.
• pdflatex tool (part of LaTeX toolset)
• make tool. This is usually present on *nix systems (Debian, macOS), for Windows you can use the GNU MCU Eclipse toolset.

For the sake of keeping it simple lets assume that working directory for intermediate files is /usr/temp-doc - this can be any user accessible directory. Doxygen and make create quite a few files that can be safely deleted afterwards, I find it good practice to keep them outside to source tree.
Also, Doxygen has the option to create subdirs for different build options, hence latex files end up in /usr/temp-doc/latex, html in /usr/temp-doc/html, etc. Please refer to Doxygen documentation for more info on this.

How to:
Go to project configuration page. Here you can edit steps to build and clean, separately for debug and release variants. It is for you to decide if you want your reference documentation to be built every time you compile or just for release.
Please note that all paths should be absolute!

• add custom step.
  Command: /usr/local/bin/doxygen (that is where my executable is located, your path might be different! On *nix systems you can try command "which doxygen" to get the location - apart from macOS, see below)
  Arguments: (none)
  Working directory: /usr/temp-doc/latex

Note for macOS users: Doxygen installation does not provide doxygen command line tool straight away. Assuming you have your Doxygen package file in /Applications/ folder, you need to make a symlink to binary that is inside the package. Open the terminal and type the line:

sudo ln -s /Applications/Doxygen.app/Contents/Resources/doxygen /usr/local/bin

Of course, target path can be whatever you choose considering the OS limitations. As there is the sudo, you will need to enter your password if you are an admin on the machine or ask your admin for help.

• add custom step.
  Command: /usr/bin/make (again, your path might be different!)
  Arguments: --directory=/usr/temp-doc/latex --ignore-errors pdf
  --ignore-all-errors limits the output from make to the sane level
  Working directory: path to the folder where intermediate build files should be created

• add custom step.
  On *nix systems:
  Command: mv
  On Windows:
  Command: move
  Arguments: /usr/temp-doc/refman.pdf /target-folder/target-file-name.pdf
  Working directory: /usr/temp-doc
  This step moves the freshly built pdf (called refman.pdf) to where we want it finally.

• DONE

Of course, this is roughly a template. You can extend this to way to remove the temporary .tex files, add clean steps, etc.

Please message me or comment if you find anything here unclear or have any questions, I am happy to explain/answer.

Kind Regards,
Artur