Introduction

This is a tutorial on generating documentations like this one in the environment of GitHub Enterprise at ZHAW. The procedure is tested under Windows 10.

Remarks: is is necessary to copy the files from doxygen-awesome-css to your repo, since GitHub Pages cannot access submodules. Also it is necessary to generate the docy locally and upload it to the repo since GitHub Actions is (currently) unavailable. If you don't want the docs destroy your repo, you could make another repo just for the dosumentation.

This tutorial was created in response to numerous requests.

Setting up the required Tools

Folder system

The documentation .html files should lay in the <repo root>/docs directory. Therefore you should create this directory in the root of your workspace.

Tools used

Doxygen @ v1.10.0
Using Doxygen with Matlab @ v1.8.0.0
doxygen-awesome-css @ v2.3.1

Install Doxygen

Download and install Doxygen.
Generate a Doxyfile and place it e.g. in the root of your project.
- You can use the Doxywizard which is a GUI to the Doxyfile
- Make sure you select the created docs folder as output folder
- in the Expert settings, configure the HTML output folder (default: html subfolder).
- I'm too lazy to write down all necessary options. Just use the Doxyfile of this Repository or find it out yourself with the provided manuals of the used tools.

Note: Make sure that you disable SHORT_NAMES and set CASE_SENSE_NAMES to YES in the Doxyfile. This makes sure that the names of generated files stay consistent which reduces the (unnecessary) data overhead on GitHub.; Config possibilities of the Doxyfile come and go. Some options might be called different when using another version.

Usage with MATLAB files (optional)

This step is only required when using .m files.

Preparing your files

Only commented lines beginning with %> will be analyzed by Doxygen. After the line starts with %> you can use the usual doxygen commands, e.g.

% ============================================================================ %
%> @brief this is an example method of the test class.
%>
%> this class is just doing something, I don't understand what.
%>
%> @param A -Just some n by m matrix
%>
%> @retval x -A number calculated from A
%>
%> @note I'm a note
%>
%> @todo Make a better example of documenting MATLAB code, you %/&%")Ã§)=%*&/!
% ============================================================================ %

Preprocessing Configuration

Download the files from Using Doxygen with Matlab and save the Perl script m2cpp.pl, e.g. in C:/Tools/Using Doxygen with Matlab/m2cpp.pl. (The file can also be fount in this repo.)
Make sure that your computer is configured to open .pl files with Perl.
Remarks
The Matlab installation contains perl under <matlab installation root>\<version>\sys\perl\win32\bin\perl.exe.
Instruct Doxygen to preprocess .m files with the Perl script by changing the FILTER_PATTERNS option of the created Doxyfile.
FILTER_PATTERNS = *.m=C:/Tools/Using Doxygen with Matlab/m2cpp.pl

Note: The steps mentioned here and more detailed information are available in the downloaded files.

Make Doxygen look pretty (optional)

This step is not required if you're just some boring engineer that doesn't care how things are looking. If you're cool, this step is mandatory.

Download doxygen-awesome-css and copy the .js and .css files placed in the root of the downloded files in some subfolder of your docs folder.
Configure Doxygen to use an alternative stylesheet by changing the option HTML_EXTRA_STYLESHEET of the Doxyfile.
HTML_EXTRA_STYLESHEET = docs/<some subfolder>/doxygen-awesome.css

Note
Depending on activated Extensions you might have to include additional .css files.

Change style and colors

You can create and include a custom .css file to change things. With doxygen-awesome-css the most important settings can be configured with variables. Check out the myStyle.css file in this repo for an example. An then add you custom .css file to the Doxyfile configuration as last file.

Configure Extensions

Configure the extensions according to the documentation of doxygen-awesome-css.

Most of them need to include additional .js files in the header. In order to make this work you have to

generate a custom doxygen html files with
doxygen -w html new_header.html new_footer.html new_stylesheet.css <YourDoxyfile>

This generates files compatible with your Doxygen version. Usually you'll need only the new_header.html.
Place the new_header.html file in some subfolder of docs and rename it.
Make the changes needed according to the documentation of doxygen-awesome-css
Instruct Doxygen to use this header by changing the HTML_HEADER option of your Doxyfile
HTML_HEADER = docs/<subfolder>/myHeader.html

Generate the actual Documentation

Run doxygen in the root of your repo. If set up correctly, the html documentation files are now inputted in the docs folder. Push the whole content to the Github server.

Configure your Repo

Warning: Even if your repo is private, the documentation will be available to every user of the GitHub Enterprise Server and also to every other user with internet access!

Note: If you're working on a private repo, you should consider just using a local webserver to view the documentation. You can ask moss@.nosp@m.zhaw.nosp@m..ch for help, if needed.

Go to Settings/Pages
Select the correct branch and the source folder /docs and press Save.
If GitHub found an index.html in the /docs folder or its subfolders, a link will appear within the Pages settings.
Copy the link
Add the html output folder at the end of the link (default: /html subfolder)
Go to Settings/Custom Tabs and add the documentation as a tab to your repo.

Table of Contents