Allow documentation to be built without header for website
Closed this issue · 2 comments
Currently, you have to run python make_docs.py. It should be optional to do this, and a plainer version of the cpp/python docs should be able to be built, then this script can just built the version for the website.
As discussed at #266, stand alone cpp docs build fails because of the reference HTML_HEADER = header.html in doc/cpp/Doxyfile . header.html doesn't exists (it gets created by make_docs.py). In source there's only header.html.template.
Standalone build succeeds by referencing the template file 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
But the problem then is that the doxygen build will use header.html.template without the style enhancements that get added by make_docs.py when it creates header.html. python make_docs.py still builds the docs in docs/cpp/html, but the html files don't get the styles like http://localhost/assets/sty.css or https://docs.fenicsproject.org/pandoc.css (even when build using make_docs.py).
Not sure if there's a clean and simple way to unravel this. make_docs.py and direct doxygen build seem to be contradictory in regards to how HTML_HEADER is defined. Bare source could provide a header.html which is initially a copy of header.html.template and gets overwritten by make_docs.py. Messy to overwrite files in the source tree though.
For the Debian (Ubuntu) builds in any case, I can switch to using make_docs.py. There are some other issues concerning privacy policy (we want the docs to work locally without net access to https://docs.fenicsproject.org/pandoc.css), and ideally want the docs to work as local files without a web server (e.g. file:///usr/share..../assets/sty.css rather than http://localhost/assets/sty.css). But they're separate issues from the basic doc build, can resolve them with debian patches.
For my part, I'm happy with using make_docs.py instead of a direct doxygen build.
in #303, The seperate doxygen and sphinx builds work independently. make_html.py has been moved inside docs/web/ and makes a copy of the python and cpp source then adds the templates to make the docs look like the FEniCS website. The intention is now that anyone building the docs uses plain sphinx/doxygen and make_html.py is only used by the CI to make the docs that are available online.
The README inside the docs folder is updated to tell users how to make the docs