|
| 1 | +# Doxygen Awesome |
| 2 | + |
| 3 | +[](https://github.com/jothepro/doxygen-awesome-css/releases/latest) |
| 4 | +[](https://github.com/jothepro/doxygen-awesome-css/blob/main/LICENSE) |
| 5 | + |
| 6 | + |
| 7 | +<div class="title_screenshot"> |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +</div> |
| 12 | + |
| 13 | +**Doxygen Awesome** is a custom CSS theme for Doxygen HTML documentation with lots of customization parameters. |
| 14 | + |
| 15 | +## Motivation |
| 16 | + |
| 17 | +I really like how the Doxygen HTML documentation is structured! But IMHO it looks a bit outdated. |
| 18 | + |
| 19 | +This theme is an attempt to update the visuals of Doxygen without changing its overall layout too much. |
| 20 | + |
| 21 | +## Features |
| 22 | + |
| 23 | +- 🌈 Clean, modern design |
| 24 | +- 🚀 Heavily customizable by adjusting CSS variables |
| 25 | +- 🧩 No changes to the HTML structure of Doxygen are required |
| 26 | +- 📱 Improved mobile usability |
| 27 | +- 🌘 Dark mode support! |
| 28 | +- 🥇 Works best with **doxygen 1.9.1** - **1.9.4** and **1.9.6** - **1.12.0** |
| 29 | + |
| 30 | +## Examples |
| 31 | + |
| 32 | +Some websites using this theme: |
| 33 | + |
| 34 | +- [Documentation of this repository](https://jothepro.github.io/doxygen-awesome-css/) |
| 35 | +- [wxWidgets](https://docs.wxwidgets.org/3.2/) |
| 36 | +- [OpenCV 5.x](https://docs.opencv.org/5.x/) |
| 37 | +- [Zephyr](https://docs.zephyrproject.org/latest/doxygen/html/index.html) |
| 38 | +- [FELTOR](https://mwiesenberger.github.io/feltor/dg/html/modules.html) |
| 39 | +- [Spatial Audio Framework (SAF)](https://leomccormack.github.io/Spatial_Audio_Framework/index.html) |
| 40 | +- [Randolf Richardson's C++ classes](https://www.randolf.ca/c++/docs/) |
| 41 | +- [libCloudSync](https://jothepro.github.io/libCloudSync/) |
| 42 | +- [libsl3](https://a4z.github.io/libsl3/) |
| 43 | + |
| 44 | +## Installation |
| 45 | + |
| 46 | +To use the theme when generating your documentation, bring the required CSS and JS files from this repository into your project. |
| 47 | + |
| 48 | +This can be done in several ways: |
| 49 | + |
| 50 | +- manually copying the files |
| 51 | +- adding the project as a Git submodule |
| 52 | +- downloading the project with CMake FetchContent |
| 53 | +- adding the project as a npm/xpm dependency |
| 54 | +- installing the theme system-wide |
| 55 | + |
| 56 | +All theme files are located in the root of this repository and start with the prefix `doxygen-awesome-`. You may not need all of them. Follow the install instructions to figure out what files are required for your setup. |
| 57 | + |
| 58 | +### Git submodule |
| 59 | +For projects that use git, add the repository as a submodule and check out the desired release: |
| 60 | + |
| 61 | +```sh |
| 62 | +git submodule add https://github.com/jothepro/doxygen-awesome-css.git |
| 63 | +cd doxygen-awesome-css |
| 64 | +git checkout v2.3.4 |
| 65 | +``` |
| 66 | + |
| 67 | +### CMake with FetchContent |
| 68 | + |
| 69 | +For project that build with CMake, the `FetchContent` module can be used to download the repository at configure-time. |
| 70 | + |
| 71 | +Add the following snippet to your `CMakeLists.txt` |
| 72 | + |
| 73 | +```cmake |
| 74 | +include(FetchContent) |
| 75 | +FetchContent_Declare( |
| 76 | + doxygen-awesome-css |
| 77 | + URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip |
| 78 | +) |
| 79 | +FetchContent_MakeAvailable(doxygen-awesome-css) |
| 80 | +
|
| 81 | +# Save the location the files were cloned into |
| 82 | +# This allows us to get the path to doxygen-awesome.css |
| 83 | +FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR) |
| 84 | +
|
| 85 | +# Generate the Doxyfile |
| 86 | +set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doc/Doxyfile.in) |
| 87 | +set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) |
| 88 | +configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) |
| 89 | +``` |
| 90 | + |
| 91 | +This downloads the latest main (but any other revision could be used) and unpacks in the build folder. The `Doxyfile.in` can reference this location in the `HTML_EXTRA_STYLESHEET` field |
| 92 | + |
| 93 | +```text |
| 94 | +HTML_EXTRA_STYLESHEET = @AWESOME_CSS_DIR@/doxygen-awesome.css |
| 95 | +``` |
| 96 | + |
| 97 | +When the configure stage of CMake is run, the `Doxyfile.in` is rendered to Doxyfile and Doxygen can be run as usual. |
| 98 | + |
| 99 | +### npm/xpm dependency |
| 100 | + |
| 101 | +In the npm ecosystem, this project can be added as a development dependency |
| 102 | +to your project: |
| 103 | + |
| 104 | +```sh |
| 105 | +cd your-project |
| 106 | +npm install https://github.com/jothepro/doxygen-awesome-css#v2.3.4 --save-dev |
| 107 | + |
| 108 | +ls -l node_module/@jothepro/doxygen-awesome-css |
| 109 | +``` |
| 110 | + |
| 111 | +Similarly, in the [xPack](https://xpack.github.io) ecosystem, this project can be added |
| 112 | +as a development dependency to an [`xpm`](https://xpack.github.io/xpm/) |
| 113 | +managed project. |
| 114 | + |
| 115 | +### System-wide |
| 116 | + |
| 117 | +You can even install the theme system-wide by running `make install`. |
| 118 | +The files will be installed to `/usr/local/share/` by default, |
| 119 | +but you can customize the install location with `make PREFIX=/my/custom/path install`. |
| 120 | + |
| 121 | +### Choosing a layout |
| 122 | + |
| 123 | +There are two layout options. Choose one of them and configure Doxygen accordingly: |
| 124 | + |
| 125 | +<div class="tabbed"> |
| 126 | + |
| 127 | +- <b class="tab-title">Base Theme</b><div class="darkmode_inverted_image"> |
| 128 | +  |
| 129 | + </div> |
| 130 | + Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled. |
| 131 | + |
| 132 | + Required files: `doxygen-awesome.css` |
| 133 | + |
| 134 | + Required `Doxyfile` configuration: |
| 135 | + ``` |
| 136 | + GENERATE_TREEVIEW = YES # optional. Also works without treeview |
| 137 | + DISABLE_INDEX = NO |
| 138 | + FULL_SIDEBAR = NO |
| 139 | + HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css |
| 140 | + HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 |
| 141 | + ``` |
| 142 | +
|
| 143 | +- <b class="tab-title">Sidebar-Only Theme</b><div class="darkmode_inverted_image"> |
| 144 | +  |
| 145 | + </div> |
| 146 | + Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work. |
| 147 | +
|
| 148 | + Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css` |
| 149 | +
|
| 150 | + Required `Doxyfile` configuration: |
| 151 | + ``` |
| 152 | +
|
| 153 | + GENERATE_TREEVIEW = YES # required! |
| 154 | + DISABLE_INDEX = NO |
| 155 | + FULL_SIDEBAR = NO |
| 156 | + HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ |
| 157 | + doxygen-awesome-css/doxygen-awesome-sidebar-only.css |
| 158 | + HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 |
| 159 | + ``` |
| 160 | +
|
| 161 | +</div> |
| 162 | +
|
| 163 | +<br> |
| 164 | +
|
| 165 | +@warning |
| 166 | +- This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen! |
| 167 | +- `HTML_COLORSTYLE` must be set to `LIGHT` since Doxygen 1.9.5! |
| 168 | +
|
| 169 | +### Further installation instructions |
| 170 | +
|
| 171 | +- [Installing extensions](docs/extensions.md) |
| 172 | +- [Customizing the theme (colors, spacing, border-radius, ...)](docs/customization.md) |
| 173 | +- [Tips and Tricks for further configuration](docs/tricks.md) |
| 174 | +
|
| 175 | +## Browser support |
| 176 | +
|
| 177 | +Tested with |
| 178 | +
|
| 179 | +- Chrome 119, Chrome 119 for Android, Chrome 119 for iOS |
| 180 | +- Safari 17, Safari for iOS 16 |
| 181 | +- Firefox 118, Firefox 120 for Android, Firefox 119 for iOS |
| 182 | +- Edge 119 |
| 183 | +- Opera 108 |
| 184 | +
|
| 185 | +
|
| 186 | +The theme does not strive to be backward compatible with (significantly) older browser versions. |
| 187 | +
|
| 188 | +
|
| 189 | +## Credits |
| 190 | +
|
| 191 | +Thanks for all the bug reports and inspiring feedback on GitHub! |
| 192 | +
|
| 193 | +Special thanks to all the contributors: |
| 194 | +<br><br> |
| 195 | +<a href="https://github.com/jothepro/doxygen-awesome-css/graphs/contributors"> |
| 196 | + <img src="https://contrib.rocks/image?repo=jothepro/doxygen-awesome-css" /> |
| 197 | +</a> |
| 198 | +
|
| 199 | +
|
| 200 | +<div class="section_buttons"> |
| 201 | +
|
| 202 | +| Read Next | |
| 203 | +|---------------------------------:| |
| 204 | +| [Extensions](docs/extensions.md) | |
| 205 | +
|
| 206 | +</div> |
0 commit comments