From b5d5b276b4d1eaefa17f5b4e21c94a8f3996d436 Mon Sep 17 00:00:00 2001 From: jothepro Date: Thu, 30 Nov 2023 13:24:39 +0100 Subject: [PATCH] improve documentation --- README.md | 31 ++++++------ docs/customization.md | 12 ++--- docs/extensions.md | 26 +++++----- docs/tricks.md | 12 ++--- include/MyLibrary/example.hpp | 89 +++++++++++++++++++---------------- 5 files changed, 92 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 70cad98..6502ff8 100644 --- a/README.md +++ b/README.md @@ -10,19 +10,19 @@ -**Doxygen Awesome** is a custom **CSS theme for Doxygen HTML-documentation** with lots of customization parameters. +**Doxygen Awesome** is a custom CSS theme for Doxygen HTML documentation with lots of customization parameters. ## Motivation -I really like how the Doxygen HTML-documentation is structured! But IMHO it looks a bit outdated. +I really like how the Doxygen HTML documentation is structured! But IMHO it looks a bit outdated. This theme is an attempt to update the visuals of Doxygen without changing its overall layout too much. ## Features - 🌈 Clean, modern design -- 🚀 Heavily customizable by adjusting CSS-variables -- 🧩 No changes to the HTML structure of Doxygen required +- 🚀 Heavily customizable by adjusting CSS variables +- 🧩 No changes to the HTML structure of Doxygen are required - 📱 Improved mobile usability - 🌘 Dark mode support! - 🥇 Works best with **doxygen 1.9.1** - **1.9.4** and **1.9.6** - **1.9.8** @@ -49,13 +49,12 @@ This can be done in several ways: - manually copying the files - adding the project as a Git submodule - adding the project as a npm/xpm dependency -- installing the theme system wide +- installing the theme system-wide 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. ### Git submodule - -For projects which use git, add the repository as a submodule and check out the desired release: +For projects that use git, add the repository as a submodule and check out the desired release: ```sh git submodule add https://github.com/jothepro/doxygen-awesome-css.git @@ -81,16 +80,18 @@ managed project. ### System-wide -You can even install the theme system-wide by running `make install`. The files will be installed to `/usr/local/share/` by default, but you can customize the install location with `make PREFIX=/my/custom/path install`. +You can even install the theme system-wide by running `make install`. +The files will be installed to `/usr/local/share/` by default, +but you can customize the install location with `make PREFIX=/my/custom/path install`. ### Choosing a layout -There is two layout options. Choose one of them and configure Doxygen accordingly: +There are two layout options. Choose one of them and configure Doxygen accordingly:
- Base Theme
- ![](img/theme-variants-base.drawio.svg){} + ![](img/theme-variants-base.drawio.svg)
Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled. @@ -125,13 +126,13 @@ There is two layout options. Choose one of them and configure Doxygen accordingl
-
+
-**Caution**: +@warning - This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen! - `HTML_COLORSTYLE` must be set to `LIGHT` since Doxygen 1.9.5! -### Further installation instructions: +### Further installation instructions - [Installing extensions](docs/extensions.md) - [Customizing the theme (colors, spacing, border-radius, ...)](docs/customization.md) @@ -147,12 +148,12 @@ Tested with - Edge 119 -The theme does not strive to be backwards compatible to (significantly) older browser versions. +The theme does not strive to be backward compatible with (significantly) older browser versions. ## Credits -Thanks for all the bug reports and inspiring feedback on github! +Thanks for all the bug reports and inspiring feedback on GitHub! Special thanks to all the contributors:

diff --git a/docs/customization.md b/docs/customization.md index a1f898d..e17fa57 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -7,7 +7,7 @@ This theme is highly customizable because a lot of things are parameterized with CSS variables. -Just to give you an idea on how flexible the styling is, click this button: +Just to give you an idea of how flexible the styling is, click this button:
Alter theme
@@ -26,7 +26,7 @@ html { } ``` -For dark-mode overrides you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not: +For dark-mode overrides, you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not:
@@ -90,11 +90,11 @@ If you miss a configuration option or find a bug, please consider [opening an is The theme overrides most colors with the `--primary-color-*` variables. -But there is a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with +But there are a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with the rest, it is recommended to adjust the [doxygen color settings](https://www.doxygen.nl/manual/customize.html#minor_tweaks_colors) -to something that matches the chosen color-scheme. +to something that matches the chosen color scheme. -For the default color-scheme, these values work out quite well: +For the default color scheme, these values work out quite well: ``` # Doxyfile @@ -105,7 +105,7 @@ HTML_COLORSTYLE_GAMMA = 113 ## Share your customizations -If you customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can to this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13). +If you have customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can do this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13). I am always curious to learn about how you made the theme look even better! diff --git a/docs/extensions.md b/docs/extensions.md index b364628..b91b8a1 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -4,7 +4,7 @@ On top of the base theme provided by `doxygen-awesome.css`, this repository comes with Javascript extensions that require additional setup steps to get them running. -The extensions require customizations in the header HTML-template. +The extensions require customizations in the header HTML template. This is how you can create the default template with Doxygen: 1. Create default header template: @@ -24,7 +24,8 @@ This is how you can create the default template with Doxygen: Adds a button next to the search bar to enable and disable the dark theme variant manually:
- + +![](img/darkmode_toggle.png){width=250px}
### Installation @@ -68,7 +69,8 @@ All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle. Shows a copy button when the user hovers over a code fragment:
- + +![](img/fragment_copy_button.png){width=490}
### Installation @@ -108,7 +110,8 @@ All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle. Provides a button on hover behind every headline to allow easy creation of a permanent link to the headline:
- + +![](img/paragraph_link.png){width=220}
Works for all headlines and for many documentation section titles. @@ -146,13 +149,14 @@ All customizations must be applied before calling `DoxygenAwesomeParagraphLink.i ## Interactive TOC {#extension-toc} -On large screens the Table of Contents (TOC) is anchored on the top right of the page. This extension visualizes the reading progress by dynamically highlighting the currently active section. +On large screens, the Table of Contents (TOC) is anchored on the top right of the page. This extension visualizes the reading progress by dynamically highlighting the currently active section. -On small screens the extension hides the TOC by default. The user can open it manually when needed: +On small screens, the extension hides the TOC by default. The user can open it manually when needed:
- + +![](img/interactive_toc_mobile.png){width=380}
### Installation @@ -192,8 +196,8 @@ This extension allows to arrange list content in tabs:
-- Tab 1 This is the content of tab 1 -- Tab 2 This is the content of tab 2 +- Tab 1 This is the content of tab 1 +- Tab 2 This is the content of tab 2
@@ -223,8 +227,8 @@ Each item in the list must start with an element that has the class `tab-title`. ```md
-- Tab 1 This is the content of tab 1 -- Tab 2 This is the content of tab 2 +- Tab 1 This is the content of tab 1 +- Tab 2 This is the content of tab 2
``` diff --git a/docs/tricks.md b/docs/tricks.md index 493a2ef..4cc3192 100644 --- a/docs/tricks.md +++ b/docs/tricks.md @@ -4,7 +4,7 @@ ## Diagrams with Graphviz {#tricks-graphviz} -To get the best looking class diagrams for your documentation, generate them with Graphviz as vector graphics with transparent background: +To get the best-looking class diagrams for your documentation, generate them with Graphviz as vector graphics with transparent background: ``` # Doxyfile @@ -13,7 +13,7 @@ DOT_IMAGE_FORMAT = svg DOT_TRANSPARENT = YES ``` -In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, all user-defined dotgraphs must be wrapped with the `interactive_dotgraph` CSS class in order for them to be rendered correctly: +In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, all user-defined dotgraphs must be wrapped with the `interactive_dotgraph` CSS class for them to be rendered correctly: ```md
@@ -28,13 +28,13 @@ In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, all user-defined dotgrap ## Disable Dark Mode {#tricks-darkmode} If you don't want the theme to automatically switch to dark mode depending on the browser preference, -you can disable dark mode by adding the `light-mode` class to the html-tag in the header template: +you can disable dark mode by adding the `light-mode` class to the HTML tag in the header template: ```html ``` -The same can be done to always enable dark-mode: +The same can be done to always enable dark mode: ```html @@ -70,7 +70,7 @@ Those properties can be changed for individual tables. ### Centering -Tables can be centered by wrapping them in the `
` HTML-tag. +Tables can be centered by wrapping them in the `
` HTML tag.
@@ -97,7 +97,7 @@ Tables can be centered by wrapping them in the `
` HTML-tag. To make tables span the full width of the page, no matter how wide the content is, wrap the table in the `full_width_table` CSS class. -@warning Apply with caution! This breaks the overflow scrolling of the table. Content might be cut of on small screens! +@warning Apply with caution! This breaks the overflow scrolling of the table. Content might be cut off on small screens!
diff --git a/include/MyLibrary/example.hpp b/include/MyLibrary/example.hpp index 36d18db..4662d80 100644 --- a/include/MyLibrary/example.hpp +++ b/include/MyLibrary/example.hpp @@ -26,50 +26,59 @@ class Example { * * ## Tables * - * The table content is scrollable if the table gets too wide. + *
+ * + * - Basic + * This theme supports normal markdown tables:
+ * | Item | Title | Description | More | + * |-----:|-------|-----------------------|--------------------------------------------| + * | 1 | Foo | A placeholder | Some lorem ipsum to make this table wider. | + * | 2 | Bar | Also a placeholder | More lorem ipsum. | + * | 3 | Baz | The third placeholder | More lorem ipsum. | + * - Centered + *
+ * A table can be centered with the `
` html tag:
+ * | Item | Title | Description | More | + * |-----:|-------|-----------------------|--------------------------------------------| + * | 1 | Foo | A placeholder | Some lorem ipsum to make this table wider. | + * | 2 | Bar | Also a placeholder | More lorem ipsum. | + * | 3 | Baz | The third placeholder | More lorem ipsum. | + *
+ * - Stretched + * A table wrapped in `
` fills the full page width. + *
+ * | Item | Title | Description | More | + * |-----:|-------|-----------------------|--------------------------------------------| + * | 1 | Foo | A placeholder | Some lorem ipsum to make this table wider. | + * | 2 | Bar | Also a placeholder | More lorem ipsum. | + * | 3 | Baz | The third placeholder | More lorem ipsum. | + *
+ * **Caution**: This will break the overflow scrolling support! + * - Complex + * Complex [Doxygen tables](https://www.doxygen.nl/manual/tables.html) are also supported as seen in @ref multi_row "this example":
+ * + * + *
Complex table
Column 1 Column 2 Column 3 + *
cell row=1+2,col=1cell row=1,col=2cell row=1,col=3 + *
cell row=2+3,col=2 cell row=2,col=3 + *
cell row=3,col=1 cell row=3,col=3 + *
+ * - Overflow Scrolling The table content is scrollable if the table gets too wide.
+ * | first_column | second_column | third_column | fourth_column | fifth_column | sixth_column | seventh_column | eighth_column | ninth_column | + * |--------------|---------------|--------------|---------------|--------------|--------------|----------------|---------------|--------------| + * | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | + * - ImagesA table can contain images:
+ * | Column 1 | Column 2 | + * |---------------------------|-------------------------------------------------| + * | ![doxygen](testimage.png) | ← the image should not be inverted in dark-mode | * - * | first_column | second_column | third_column | fourth_column | fifth_column | sixth_column | seventh_column | eighth_column | ninth_column | - * |--------------|---------------|--------------|---------------|--------------|--------------|----------------|---------------|--------------| - * | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | * - * A table can contain images: + *
* - * | Column 1 | Column 2 | - * |---------------------------|-------------------------------------------------| - * | ![doxygen](testimage.png) | ← the image should not be inverted in dark-mode | + * ## Diagrams + * + * Graphviz diagrams support dark mode and can be scrolled once they get too wide: * - * Complex [Doxygen tables](https://www.doxygen.nl/manual/tables.html) are also supported as seen in @ref multi_row "this example": - * - * - * - *
Complex table
Column 1 Column 2 Column 3 - *
cell row=1+2,col=1cell row=1,col=2cell row=1,col=3 - *
cell row=2+3,col=2 cell row=2,col=3 - *
cell row=3,col=1 cell row=3+4,col=3 - *
cell row=4,col=1+2 - *
cell row=5,col=1 cell row=5,col=2+3 - *
cell row=6+7,col=1+2 cell row=6,col=3 - *
cell row=7,col=3 - *
cell row=8,col=1 cell row=8,col=2\n - * - *
Inner cell row=1,col=1Inner cell row=1,col=2 - *
Inner cell row=2,col=1Inner cell row=2,col=2 - *
- * 		cell row=8,col=3 - *
    - *
  • Item 1 - *
  • Item 2 - *
- *
- * - * A table can be centered with the `
` html tag: - *
- * | Foo | Bar | Baz | FooBar | - * |-------------|----------------|---------------------------|-------------| - * | Lorem imsum | dolor sit amet | cenectetur adipisici elit | At vero eos | - *
- * - * Embedded Graphviz graphs support dark mode and can be scrolled once they get too wide: * \dot Graphviz with a caption * digraph example { * node [fontsize="12"];