Doxygen for 3.5

Todos:

• empty doxyerr.log as much as possible
• Anything interesting to fix in doxygen.log? There is a warning "warning: Tag 'COLS_IN_ALPHA_INDEX' at line 114 of file 'Doxyfile' has become obsolete." However, this concerns dune-common/doc/doxygen/Doxystyle, not dumux.
• does doc/doxygen/modules.txt match the folder structure?
• Check for missing ingroup
• Check for wrong ingroup
• check correct display of the equations
• correct linking of the sites (see sanitizelinks.sh for previous fixes)
• does work on the dumux website as well?
• under Namespaces - Namespace List spot some undocumented classes
• does the documentation make sense? spot mistakenly made copy& paste?

For possible reference of a future doxygen dude: The documentation is built by running make doc in the dumux build folder. One way to switch doxygen versions is to:

• download the doxygen git repository from https://github.com/doxygen/doxygen.git
• checkout the branch you want, e.g. Release_1_8_17
• the first time do: mkdir build, cd build, cmake -G "Unix Makefiles" ..
• always do in the doxygen build directory: make, sudo make install
• the first time do: export PATH=/usr/local/bin/doxygen:$PATH
• delete the dumux build folder and rerun dunecontrol for dumux ./dune-common/bin/dunecontrol --opts=./dumux/cmake.opts --only=dumux all

After Changes in scr/doxygen.cpp delete the build folder an recreate it.

Related MRs: !3027 (merged), !3029 (merged)

changed milestone to %3.5

added Documentation Dumux Day labels

assigned to @melaniel

changed the description

I use Doxygen Release_1_9_3 with the change

diff --git a/src/doxygen.cpp b/src/doxygen.cpp
index 4686fce0..f83c643b 100644
--- a/src/doxygen.cpp
+++ b/src/doxygen.cpp
@@ -11928,6 +11928,7 @@ void parseInput()
   g_s.begin("Searching for members imported via using declarations...\n");
   // this should be after buildTypedefList in order to properly import
   // used typedefs
+  findUsingDeclImports(root.get()); // may introduce new members !
   findUsingDeclarations(root.get(),TRUE);  // do for python packages first
   findUsingDeclarations(root.get(),FALSE); // then the rest
   g_s.end();
@@ -11994,7 +11995,6 @@ void parseInput()
   g_s.begin("Searching for member function documentation...\n");
   findObjCMethodDefinitions(root.get());
   findMemberDocumentation(root.get()); // may introduce new members !
-  findUsingDeclImports(root.get()); // may introduce new members !
 
   transferRelatedFunctionDocumentation();
   transferFunctionDocumentation();

and in dumux

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 2a9b71338..b04390b76 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1,2 +1,2 @@
 add_subdirectory(doxygen)
-add_subdirectory(handbook)
+#add_subdirectory(handbook)

mentioned in issue #1129 (closed)

changed the description

marked the checklist item Anything interesting to fix in doxygen.log? as completed

changed the description

marked the checklist item empty doxyerr.log as much as possible as completed

changed the description

The dumux-website -ci (dockerimage) still uses doxygen 1.8.17 which was released on 27-12-2019. The new series 1.9.0 appeared 27th December 2020, now we have 1.9.3. The changelog shows some work https://www.doxygen.nl/manual/changelog.html. I think it is not that hard also to upgrade the docker-image.

But this could break the doxygen-documentation of the older releases. Either we do not care or we have to setup the build of the whole webpage with different doxygen versions. But this is as webpage topic.

Currently, we have doxygen beginning with 3.1 on the webpage. So we could try locally if the documentation of 3.1, 3.2, 3.3 or 3.4 break, right?

I started building the documentation of 3.1.0 with doxygen 1.9.3 and will report here.

Even for release 3.1.0, it doxygen finishes the build properly.

To me, it looks like there won't be a problem using doxygen 1.9.3 with

diff --git a/src/doxygen.cpp b/src/doxygen.cpp
index 4686fce0..f83c643b 100644
--- a/src/doxygen.cpp
+++ b/src/doxygen.cpp
@@ -11928,6 +11928,7 @@ void parseInput()
   g_s.begin("Searching for members imported via using declarations...\n");
   // this should be after buildTypedefList in order to properly import
   // used typedefs
+  findUsingDeclImports(root.get()); // may introduce new members !
   findUsingDeclarations(root.get(),TRUE);  // do for python packages first
   findUsingDeclarations(root.get(),FALSE); // then the rest
   g_s.end();
@@ -11994,7 +11995,6 @@ void parseInput()
   g_s.begin("Searching for member function documentation...\n");
   findObjCMethodDefinitions(root.get());
   findMemberDocumentation(root.get()); // may introduce new members !
-  findUsingDeclImports(root.get()); // may introduce new members !
 
   transferRelatedFunctionDocumentation();
   transferFunctionDocumentation();

for all doxygen documentation on the dumux website.

Ok, I found something that does not work. For release 3.2.0 (maybe also for 3.1.0, there I did not check it) doxygen 1.9.3 breaks the bibliography from reference 15 onward. On the webpage version (with doxygen 1.8.17) the bibliography is fine. For dumux master and doxygen 1.9.3, the bibliography is fine as well.

changed the description

changed the description

marked the checklist item does doc/doxygen/modules.txt match the folder structure? as completed

marked the checklist item Check for missing ingroup as completed

marked the checklist item Check for missing ingroup as incomplete

marked the checklist item Check for missing ingroup as completed

marked the checklist item Check for missing ingroup as incomplete

marked the checklist item Check for wrong ingroup as completed

marked the checklist item Check for missing ingroup as completed

marked the checklist item does work on the dumux website as well? as completed

marked the checklist item check correct display of the equations as completed

marked the checklist item correct linking of the sites (see sanitizelinks.sh for previous fixes) as completed

changed the description

marked the checklist item under Namespaces - Namespace List spot some undocumented classes as completed

marked the checklist item does the documentation make sense? spot mistakenly made copy& paste? as completed

mentioned in merge request !3029 (merged)

closed with merge request !3029 (merged)

mentioned in commit c0098a92