doxygen tags obsolete (TCL_SUBST etc)
Closed this issue · 5 comments
cpp doc build in 0.3.0 fails,
$doxygen -u
warning: Tag 'TCL_SUBST' at line 247 of file 'Doxyfile' has become obsolete.
This tag has been removed.
warning: Tag 'COLS_IN_ALPHA_INDEX' at line 1067 of file 'Doxyfile' has become obsolete.
This tag has been removed.
warning: Tag 'PERL_PATH' at line 2132 of file 'Doxyfile' has become obsolete.
This tag has been removed.
warning: Tag 'MSCGEN_PATH' at line 2154 of file 'Doxyfile' has become obsolete.
This tag has been removed.
Configuration file 'Doxyfile' updated.
With doxygen -u, the -u flag updates the obsolete tags so the doc build proceeds. Without -u it fails.
This is with doxygen 1.9.1, building on Debian unstable.
Attn: #45
As part of the tags update, HTML_HEADER should be updated from header.html to header.html.template (the file in doc/cpp)
How are you building the documentation? Running python make_docs.py should create all the necessary files. I've added a README to the docs folder in #295 stating this
I've just been running
cd doc/cpp; doxygen
after building the cpp library.
I'll check the instructions in the new README.
I've opened #296. The stuff that make_docs.py does makes the docs look nice for the website, but it should be possible to build the standalone docs if you don't want the custom styling.
Looking closer the warning about the obsolete TAGS wasn't the thing that was preventing doxygen (called directly) from building docs as such. It was the reference HTML_HEADER = header.html in doc/cpp/Doxyfile that made it fail. I created a patch to reference header.html.template instead,
Index: fenics-basix/doc/cpp/Doxyfile
===================================================================
--- fenics-basix.orig/doc/cpp/Doxyfile 2021-09-09 02:58:21.778289641 +0300
+++ fenics-basix/doc/cpp/Doxyfile 2021-09-09 02:58:48.819173344 +0300
@@ -1116,7 +1116,7 @@
# of the possible markers and block names see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_HEADER = header.html
+HTML_HEADER = header.html.template
# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
# generated HTML page. If the tag is left blank doxygen will generate a standard
so that's how I've been building docs (with cd doc/cpp; doxygen). It still warns about the obsolete tags (since I didn't use doyxgen -u but the doc build succeeds. I'll add a comment on this patch at #296 for standalone build.
Your python3 make_html.py does work, I can use it (I just didn't know about it).
I notice that what make_html.py does is to create the missing header.html. So when it launches doxygen it's able to build the docs. But it still warns about the obsolete tags.
Should the source files themselves be updated for the tags? Or should make_html.py use doxygen -u at l.98 ?
Line 98 in 0902318