Documentation: Doxygen wf

[Davknapp]

Closes #1853

changes the update_doxygen workflow to a workflow that checks the output of doxygen for any warnings and fails if there are any.

All these boxes must be checked by the AUTHOR before requesting review:

• The PR is small enough to be reviewed easily. If not, consider splitting up the changes in multiple PRs.
• The title starts with one of the following prefixes: Documentation:, Bugfix:, Feature:, Improvement: or Other:.
• If the PR is related to an issue, make sure to link it.
• The author made sure that, as a reviewer, he/she would check all boxes below.

All these boxes must be checked by the REVIEWERS before merging the pull request:

As a reviewer please read through all the code lines and make sure that the code is fully understood, bug free, well-documented and well-structured.

General

• The reviewer executed the new code features at least once and checked the results manually.
• The code follows the t8code coding guidelines.
• New source/header files are properly added to the CMake files.
• The code is well documented. In particular, all function declarations, structs/classes and their members have a proper doxygen documentation.
• All new algorithms and data structures are sufficiently optimal in terms of memory and runtime (If this should be merged, but there is still potential for optimization, create a new issue).

Tests

• The code is covered in an existing or new test case using Google Test.
• The code coverage of the project (reported in the CI) should not decrease. If coverage is decreased, make sure that this is reasonable and acceptable.
• Valgrind doesn't find any bugs in the new code. This script can be used to check for errors; see also this wiki article.

If the Pull request introduces code that is not covered by the github action (for example coupling with a new library):

• Should this use case be added to the github action?
• If not, does the specific use case compile and all tests pass (check manually).

Scripts and Wiki

• If a new directory with source files is added, it must be covered by the script/find_all_source_files.scp to check the indentation of these files.
• If this PR introduces a new feature, it must be covered in an example or tutorial and a Wiki article.

License

• The author added a BSD statement to doc/ (or already has one).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.66%. Comparing base (1124119) to head (5739755).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1854   +/-   ##
=======================================
  Coverage   75.66%   75.66%           
=======================================
  Files         105      105           
  Lines       18646    18646           
=======================================
  Hits        14109    14109           
  Misses       4537     4537           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sandro-elsweijer]

We can use the container to have the dependencies pre-installed

Suggested change

	runs-on: ubuntu-latest
	runs-on: ubuntu-latest
	container: dlramr/t8code-ubuntu:t8-dependencies

[sandro-elsweijer]

Suggested change

	# This github CI script runs on every push or merged pr on the main branch.
	# It generates the doxygen documentation of the main branch and uploads it
	# to the t8code website
	# This github CI script runs on every push on a feature branch and in the merge queue.
	# It checks if the doxygen documentation can be built without errors and warnings.

[sandro-elsweijer]

We can pipe the error output into a separate file and then check if the file is empty. If not, there are warnings/errors. Afterwards we can just upload the error file and it contains only the relevant output.

Suggested change

	run: cd build && cd doc && doxygen Doxyfile >> output 2>&1
	- name: check for doxygen warnings
	run: |
	if grep -i warning build/doc/output; then
	echo "Doxygen warnings found!"
	exit 1
	else
	echo "No doxygen warnings found."
	fi
	run: cd build && cd doc && doxygen Doxyfile >> doxygen.out 2> doxygen.err
	- name: check for doxygen warnings
	run: |
	if [ ! -s build/doc/doxygen.err ]; then
	echo "Doxygen warnings found!"
	exit 1
	else
	echo "No doxygen warnings found."
	fi

[sandro-elsweijer]

path missed build/ and as already mentioned we can just upload the errors

Suggested change

	name: doxygen-output
	path: doc/output
	name: doxygen-errors
	path: build/doc/doxygen.err

[sandro-elsweijer]

In the container we can build the documentation with the dependencies. We can also build in debug to also check if the debug functions all have their documentation. MPI can also be enabled here, but I do not know if we have functions which are just documented when building with MPI. But it can also not hurt.

Suggested change

	run: mkdir build && cd build && cmake ../ -DT8CODE_BUILD_DOCUMENTATION=ON -DT8CODE_ENABLE_MPI=OFF
	run: mkdir build && cd build && cmake ../ \
	-DT8CODE_BUILD_DOCUMENTATION=ON \
	-DCMAKE_BUILD_TYPE=Debug \
	-DT8CODE_ENABLE_VTK=ON -DVTK_DIR=/usr/local/lib/cmake/vtk-9.1 \
	-DT8CODE_ENABLE_OCC=ON \
	-DT8CODE_ENABLE_NETCDF=ON

[sandro-elsweijer]

Suggested change

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

[sandro-elsweijer]

If we run in the container we do not need this

Suggested change

	run: sudo apt-get update && sudo apt-get upgrade -y
	# This step is necessary to get the newest package data
	- name: Install zlib
	run: sudo apt-get install libz-dev
	- name: Install doxygen
	run: sudo apt-get install doxygen-latex
	run: sudo apt-get update && sudo apt-get upgrade -y