[doc] optionally use doxygen HTML API docs rather than breathe/exhale-generated HTML #440
Conversation
There was a problem hiding this comment.
Pull request overview
This PR modernizes the SeQuant documentation build system by making Doxygen HTML generation the default mode and deprecating the slower Breathe/Exhale integration. The changes include adopting the modern Doxygen Awesome CSS theme, removing legacy jQuery-based navigation components (SmartMenus, Bootstrap addons), and adding a project logo.
Key changes:
- Introduced
SEQUANT_BUILD_DOCS_API_BREATHEEXHALEoption to toggle between standalone Doxygen HTML (default, faster) and Breathe/Exhale integration (optional, slower but integrated with Sphinx) - Replaced legacy Bootstrap/jQuery styling with modern Doxygen Awesome CSS theme
- Added minimum Doxygen version constraint (1.9.6) and project logo
Reviewed changes
Copilot reviewed 16 out of 20 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
doc/CMakeLists.txt |
Added conditional logic for Doxygen HTML vs XML output, integrated doxygen-awesome-css, and configured API reference content dynamically |
doc/.doxygen/Doxyfile.in |
Updated Doxygen configuration with new branding, modern settings, and conditional HTML/XML generation |
doc/developer/documentation.rst |
Updated documentation to describe both standalone Doxygen and Breathe/Exhale modes |
doc/index.rst |
Updated API reference link to point to new api.rst page |
doc/api.rst.in |
Template for API reference page with conditional content |
doc/.gitignore |
Added api.rst to ignored files |
external/versions.cmake |
Added minimum Doxygen version constraint (1.9.6) |
doc/images/logo.png |
Added SeQuant logo (binary file) |
doc/.doxygen/header.html |
Replaced Bootstrap/jQuery-based header with modern Doxygen template including dark mode toggle |
doc/.doxygen/layout.xml |
Updated to modern Doxygen 2.0 layout format |
doc/.doxygen/*.js, *.css, addons/* |
Removed legacy SmartMenus jQuery plugins and Bootstrap styling |
doc/.doxygen/README.md |
Removed outdated maintainer notes |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): | ||
| # MATHJAX_EXTENSIONS = ams | ||
| # This tag requires that the tag USE_MATHJAX is set to YES. | ||
|
|
There was a problem hiding this comment.
MATHJAX_RELPATH is set to http://cdn.mathjax.org/mathjax/latest, which loads JavaScript over HTTP. This allows a network attacker to inject arbitrary code into your documentation pages via MITM, leading to script execution when developers or users view the docs. Use HTTPS and a current CDN, e.g., set:
MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2/ || https://cdn.jsdelivr.net/npm/mathjax@3/(or host MathJax locally)
doc/CMakeLists.txt
Outdated
| include(FetchContent) | ||
| FetchContent_Declare( | ||
| doxygen-awesome-css | ||
| URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip |
There was a problem hiding this comment.
FetchContent_Declare(doxygen-awesome-css ... URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip) downloads a moving ZIP from an unpinned branch without any integrity verification. If the upstream repository or the connection is compromised, malicious CSS/JS can be injected into your generated docs and executed in viewers’ browsers. Pin to a specific tag/commit and add an expected hash (e.g., URL_HASH MD5=<...> or switch to a vendored/submodule dependency) to ensure integrity.
| URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip | |
| URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v2.2.0.zip | |
| URL_HASH SHA256=7e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2e2 |
…T_BUILD_DOCS_API_BREATHEEXHALE=OFF (default) to use Doxygen-generated HTML API docs. this also refreshes doxygen to use doxygen awesome css theme
evaleev
force-pushed
the
feature/optionally-use-dox-rather-than-exhale
branch
from
3777509 to
7b9df23
Compare
|
I think this broke the API reference on the github pages build, the page now links to https://valeevgroup.github.io/.doxygen/html/index.html which gives me a 404, the old link https://valeevgroup.github.io/SeQuant/genindex.html is still there but is an empty table. |
If configured with
SEQUANT_BUILD_DOCS_API_BREATHEEXHALE=ONthen breathe/exhale are used to generate API docs, else (default) doxygen HTML is used directly.This pull request also removes legacy SmartMenus jQuery plugin addons and related documentation for Bootstrap and keyboard navigation from the Doxygen documentation setup. These changes help clean up unused or outdated frontend assets and simplify the documentation build process. Doxygen now uses awesome CSS to look awesome.
Documentation Cleanup
doc/.doxygen/README.mdfile, which contained build instructions and maintainer notes for Doxygen and its Bootstrap extensions.