Skip to content

Commit

Permalink
improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@jothepro
jothepro committed Nov 30, 2023
1 parent 8fe5ac3 commit b5d5b27
Show file tree
Hide file tree
Showing 5 changed files with 92 additions and 78 deletions.
31 changes: 16 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,19 @@

</div>

**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**
Expand All @@ -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
Expand All @@ -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:

<div class="tabbed">

- <b class="tab-title">Base Theme</b><div class="darkmode_inverted_image">
![](img/theme-variants-base.drawio.svg){}
![](img/theme-variants-base.drawio.svg)
</div>
Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled.

Expand Down Expand Up @@ -125,13 +126,13 @@ There is two layout options. Choose one of them and configure Doxygen accordingl

</div>

<br>
<br>

**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)
Expand All @@ -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:
<br><br>
Expand Down
12 changes: 6 additions & 6 deletions docs/customization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

<div class="alter-theme-button" onclick="toggle_alternative_theme()" onkeypress="if (event.keyCode == 13) toggle_alternative_theme()" tabindex=0>Alter theme</div>

Expand All @@ -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:

<div class="tabbed">

Expand Down Expand Up @@ -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
Expand All @@ -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!

Expand Down
26 changes: 15 additions & 11 deletions docs/extensions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:

<div class="darkmode_inverted_image bordered_image">
<img width=250 src="darkmode_toggle.png" />

![](img/darkmode_toggle.png){width=250px}
</div>

### Installation
Expand Down Expand Up @@ -68,7 +69,8 @@ All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle.
Shows a copy button when the user hovers over a code fragment:
<div class="darkmode_inverted_image bordered_image">
<img width=490 src="fragment_copy_button.png"/>
![](img/fragment_copy_button.png){width=490}
</div>
### Installation
Expand Down Expand Up @@ -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:
<div class="darkmode_inverted_image bordered_image">
<img width=220 src="paragraph_link.png"/>
![](img/paragraph_link.png){width=220}
</div>
Works for all headlines and for many documentation section titles.
Expand Down Expand Up @@ -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:
<div class="darkmode_inverted_image bordered_image">
<img width=380 src="interactive_toc_mobile.png" />
![](img/interactive_toc_mobile.png){width=380}
</div>
### Installation
Expand Down Expand Up @@ -192,8 +196,8 @@ This extension allows to arrange list content in tabs:

<div class="tabbed">

- <span class="tab-title">Tab 1</span> This is the content of tab 1
- <span class="tab-title">Tab 2</span> This is the content of tab 2
- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2

</div>

Expand Down Expand Up @@ -223,8 +227,8 @@ Each item in the list must start with an element that has the class `tab-title`.
```md
<div class="tabbed">
- <span class="tab-title">Tab 1</span> This is the content of tab 1
- <span class="tab-title">Tab 2</span> This is the content of tab 2
- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2
</div>
```
Expand Down
12 changes: 6 additions & 6 deletions docs/tricks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
<div class="interactive_dotgraph">
Expand All @@ -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
<html xmlns="http://www.w3.org/1999/xhtml" class="light-mode">
```

The same can be done to always enable dark-mode:
The same can be done to always enable dark mode:

```html
<html xmlns="http://www.w3.org/1999/xhtml" class="dark-mode">
Expand Down Expand Up @@ -70,7 +70,7 @@ Those properties can be changed for individual tables.

### Centering

Tables can be centered by wrapping them in the `<center>` HTML-tag.
Tables can be centered by wrapping them in the `<center>` HTML tag.

<div class="tabbed">

Expand All @@ -97,7 +97,7 @@ Tables can be centered by wrapping them in the `<center>` 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!

<div class="tabbed">

Expand Down
89 changes: 49 additions & 40 deletions include/MyLibrary/example.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,50 +26,59 @@ class Example {
*
* ## Tables
*
* The table content is scrollable if the table gets too wide.
* <div class="tabbed">
*
* - <b class="tab-title">Basic</b>
* This theme supports normal markdown tables:<br>
* | 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. |
* - <b class="tab-title">Centered</b>
* <center>
* A table can be centered with the `<center>` html tag:<br>
* | 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. |
* </center>
* - <b class="tab-title">Stretched</b>
* A table wrapped in `<div class="full_width_table">` fills the full page width.
* <div class="full_width_table">
* | 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. |
* </div>
* **Caution**: This will break the overflow scrolling support!
* - <b class="tab-title">Complex</b>
* Complex [Doxygen tables](https://www.doxygen.nl/manual/tables.html) are also supported as seen in @ref multi_row "this example":<br>
* <table>
* <caption id="multi_row">Complex table</caption>
* <tr><th>Column 1 <th>Column 2 <th>Column 3
* <tr><td rowspan="2">cell row=1+2,col=1<td>cell row=1,col=2<td>cell row=1,col=3
* <tr><td rowspan="2">cell row=2+3,col=2 <td>cell row=2,col=3
* <tr><td>cell row=3,col=1 <td>cell row=3,col=3
* </table>
* - <b class="tab-title">Overflow Scrolling</b> The table content is scrollable if the table gets too wide.<br>
* | 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 |
* - <b class="tab-title">Images</b>A table can contain images:<br>
* | 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:
* </div>
*
* | 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":
*
* <table>
* <caption id="multi_row">Complex table</caption>
* <tr><th>Column 1 <th>Column 2 <th>Column 3
* <tr><td rowspan="2">cell row=1+2,col=1<td>cell row=1,col=2<td>cell row=1,col=3
* <tr><td rowspan="2">cell row=2+3,col=2 <td>cell row=2,col=3
* <tr><td>cell row=3,col=1 <td rowspan="2">cell row=3+4,col=3
* <tr><td colspan="2">cell row=4,col=1+2
* <tr><td>cell row=5,col=1 <td colspan="2">cell row=5,col=2+3
* <tr><td colspan="2" rowspan="2">cell row=6+7,col=1+2 <td>cell row=6,col=3
* <tr> <td>cell row=7,col=3
* <tr><td>cell row=8,col=1 <td>cell row=8,col=2\n
* <table>
* <tr><td>Inner cell row=1,col=1<td>Inner cell row=1,col=2
* <tr><td>Inner cell row=2,col=1<td>Inner cell row=2,col=2
* </table>
* <td>cell row=8,col=3
* <ul>
* <li>Item 1
* <li>Item 2
* </ul>
* </table>
*
* A table can be centered with the `<center>` html tag:
* <center>
* | Foo | Bar | Baz | FooBar |
* |-------------|----------------|---------------------------|-------------|
* | Lorem imsum | dolor sit amet | cenectetur adipisici elit | At vero eos |
* </center>
*
* 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"];
Expand Down

0 comments on commit b5d5b27

Please sign in to comment.