The look of every ShipSoft Doxygen reference: CERN blue (Pantone 286 C,
#0033a0), the SHiP wheel as logo and favicon, light and dark mode, and a
footer linking to the SHiP Software documentation.
It shares its design tokens with the Zensical theme of
ShipSoft/Documentation, so a colour
change goes into both ship-doxygen.css here and docs/stylesheets/ship.css
there.
The theme is doxygen-awesome-css
v2.5.0 (MIT, see LICENSE.doxygen-awesome) in its sidebar-only layout, with
the dark-mode toggle, copy buttons, paragraph links, interactive TOC and tabs,
plus ship-doxygen.css on top. The scripts and the favicon are wired in through
footer.html, which only uses standard Doxygen placeholders and works with
Doxygen 1.9.8 (what ubuntu-latest installs) and newer.
The doxygen-pages.yml and doxygen-gh-pages.yml workflows apply the theme by
default. Projects don't need to copy anything or change their Doxyfile. Pass
theme: false to build without it.
Clone this repository and run the wrapper from the project's root:
/path/to/ShipSoft/.github/doxygen-theme/doxygen-ship doxygen/Doxyfiledoxygen-ship sets SHIP_DOXYGEN_THEME to its own folder and feeds Doxygen the
project's Doxyfile followed by @INCLUDE = $SHIP_DOXYGEN_THEME/Doxyfile.ship.
Because the theme comes last, its HTML settings (logo, footer, stylesheets,
colours, tree view, SVG graphs) win over the project's.
doxygen-awesome-interactive-toc.jscarries one local patch, markedSHiP patch: upstream registers the scroll listener once per TOC entry, so long TOCs re-run the update many times per scroll event. Keep the patch when updating doxygen-awesome, unless upstream has fixed it.HTML_COLORSTYLE = LIGHTneeds Doxygen 1.9.5 or newer.- The dark-mode script loads from the footer, so a page opened in dark mode
shows light for a few milliseconds. Moving the
<script>tags into a customHTML_HEADERwould avoid that, but the header would have to be generated for a specific Doxygen version. - Set
PROJECT_BRIEFin the project's Doxyfile so the title band shows a one line description next to the name.