[v3,03/10] Documentation: Enable doxygen-awesome-css
diff mbox series

Message ID 20250917201742.16406-4-laurent.pinchart@ideasonboard.com
State Accepted
Headers show
Series
  • Documentation theming update
Related show

Commit Message

Laurent Pinchart Sept. 17, 2025, 8:17 p.m. UTC 
From: Stefan Klug <stefan.klug@ideasonboard.com>

Include doxygen-awesome-css in the doxygen config.

The project's documentation indicated that the HTML_COLORSTYLE option
needs to be set to LIGHT starting with Doxygen 1.9.5. The reason isn't
explained, and tests have not shown any noticeable difference with
Doxygen 1.9.5, 1.13.2 and 1.14.0.

Unlike Doxygen itself that generates different CSS files depending on
the HTML color style, doxygen-awesome-css use the same CSS that defaults
to auto-light, and relies on adding "light-mode" to the class of the
<html> element manually to disable dark mode.

As we don't this, doxygen-awesome-css effectively operates in auto-light
mode. Given that setting HTML_COLORSTYLE to LIGHT makes no visible
difference, leave the option unset to default to auto-light mode that
matches the actual behaviour.

Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
Changes since v2:

- Drop HTML_COLORSTYLE
- Drop GENERATE_TREEVIEW=YES as it is the default

Changes since v1:

- Fix ordering of configuration options
- Use TOP_SRCDIR instead of CURRENT_SRCDIR to avoid introducing a new
  variable
---
 Documentation/Doxyfile-common.in | 3 +++
 1 file changed, 3 insertions(+)

Comments

Stefan Klug Sept. 18, 2025, 7 a.m. UTC | #1 
Hi Laurent,

Thank you for the update.

Quoting Laurent Pinchart (2025-09-17 22:17:34)
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> Include doxygen-awesome-css in the doxygen config.
> 
> The project's documentation indicated that the HTML_COLORSTYLE option
> needs to be set to LIGHT starting with Doxygen 1.9.5. The reason isn't
> explained, and tests have not shown any noticeable difference with
> Doxygen 1.9.5, 1.13.2 and 1.14.0.
> 
> Unlike Doxygen itself that generates different CSS files depending on
> the HTML color style, doxygen-awesome-css use the same CSS that defaults
> to auto-light, and relies on adding "light-mode" to the class of the
> <html> element manually to disable dark mode.
> 
> As we don't this, doxygen-awesome-css effectively operates in auto-light

s/don't/don't do/

> mode. Given that setting HTML_COLORSTYLE to LIGHT makes no visible
> difference, leave the option unset to default to auto-light mode that
> matches the actual behaviour.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Can I put my reviewed-by on something I signed off?

Anyways:
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com> 

Regards,
Stefan

> ---
> Changes since v2:
> 
> - Drop HTML_COLORSTYLE
> - Drop GENERATE_TREEVIEW=YES as it is the default
> 
> Changes since v1:
> 
> - Fix ordering of configuration options
> - Use TOP_SRCDIR instead of CURRENT_SRCDIR to avoid introducing a new
>   variable
> ---
>  Documentation/Doxyfile-common.in | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> index c9527da03ed5..23a0e3626f9d 100644
> --- a/Documentation/Doxyfile-common.in
> +++ b/Documentation/Doxyfile-common.in
> @@ -54,6 +54,9 @@ EXCLUDE_SYMBOLS        = libcamera::BoundMethodArgs \
>  
>  IMAGE_PATH             = "@TOP_SRCDIR@/Documentation/images"
>  
> +HTML_EXTRA_STYLESHEET  = "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome.css" \
> +                         "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome-sidebar-only.css"
> +
>  GENERATE_LATEX         = NO
>  
>  MACRO_EXPANSION        = YES
> -- 
> Regards,
> 
> Laurent Pinchart
>
Barnabás Pőcze Sept. 18, 2025, 10:16 a.m. UTC | #2 
2025. 09. 17. 22:17 keltezéssel, Laurent Pinchart írta:
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> Include doxygen-awesome-css in the doxygen config.
> 
> The project's documentation indicated that the HTML_COLORSTYLE option
> needs to be set to LIGHT starting with Doxygen 1.9.5. The reason isn't
> explained, and tests have not shown any noticeable difference with
> Doxygen 1.9.5, 1.13.2 and 1.14.0.
> 
> Unlike Doxygen itself that generates different CSS files depending on
> the HTML color style, doxygen-awesome-css use the same CSS that defaults
> to auto-light, and relies on adding "light-mode" to the class of the
> <html> element manually to disable dark mode.
> 
> As we don't this, doxygen-awesome-css effectively operates in auto-light
> mode. Given that setting HTML_COLORSTYLE to LIGHT makes no visible
> difference, leave the option unset to default to auto-light mode that
> matches the actual behaviour.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> Changes since v2:
> 
> - Drop HTML_COLORSTYLE
> - Drop GENERATE_TREEVIEW=YES as it is the default
> 
> Changes since v1:
> 
> - Fix ordering of configuration options
> - Use TOP_SRCDIR instead of CURRENT_SRCDIR to avoid introducing a new
>    variable
> ---

Not setting HTML_COLORSTYLE=LIGHT makes it actually look better in dark mode
when using doxygen 1.14.0 ( avoids https://github.com/jothepro/doxygen-awesome-css/issues/185 ).

Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>


>   Documentation/Doxyfile-common.in | 3 +++
>   1 file changed, 3 insertions(+)
> 
> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> index c9527da03ed5..23a0e3626f9d 100644
> --- a/Documentation/Doxyfile-common.in
> +++ b/Documentation/Doxyfile-common.in
> @@ -54,6 +54,9 @@ EXCLUDE_SYMBOLS        = libcamera::BoundMethodArgs \
>   
>   IMAGE_PATH             = "@TOP_SRCDIR@/Documentation/images"
>   
> +HTML_EXTRA_STYLESHEET  = "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome.css" \
> +                         "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome-sidebar-only.css"
> +
>   GENERATE_LATEX         = NO
>   
>   MACRO_EXPANSION        = YES
Laurent Pinchart Sept. 18, 2025, 2:21 p.m. UTC | #3 
On Thu, Sep 18, 2025 at 09:00:10AM +0200, Stefan Klug wrote:
> Quoting Laurent Pinchart (2025-09-17 22:17:34)
> > From: Stefan Klug <stefan.klug@ideasonboard.com>
> > 
> > Include doxygen-awesome-css in the doxygen config.
> > 
> > The project's documentation indicated that the HTML_COLORSTYLE option
> > needs to be set to LIGHT starting with Doxygen 1.9.5. The reason isn't
> > explained, and tests have not shown any noticeable difference with
> > Doxygen 1.9.5, 1.13.2 and 1.14.0.
> > 
> > Unlike Doxygen itself that generates different CSS files depending on
> > the HTML color style, doxygen-awesome-css use the same CSS that defaults
> > to auto-light, and relies on adding "light-mode" to the class of the
> > <html> element manually to disable dark mode.
> > 
> > As we don't this, doxygen-awesome-css effectively operates in auto-light
> 
> s/don't/don't do/
> 
> > mode. Given that setting HTML_COLORSTYLE to LIGHT makes no visible
> > difference, leave the option unset to default to auto-light mode that
> > matches the actual behaviour.
> > 
> > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> 
> Can I put my reviewed-by on something I signed off?

Sure, you've reviewed the changes compared to your initial version.

> Anyways:
> Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com> 
> 
> > ---
> > Changes since v2:
> > 
> > - Drop HTML_COLORSTYLE
> > - Drop GENERATE_TREEVIEW=YES as it is the default
> > 
> > Changes since v1:
> > 
> > - Fix ordering of configuration options
> > - Use TOP_SRCDIR instead of CURRENT_SRCDIR to avoid introducing a new
> >   variable
> > ---
> >  Documentation/Doxyfile-common.in | 3 +++
> >  1 file changed, 3 insertions(+)
> > 
> > diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> > index c9527da03ed5..23a0e3626f9d 100644
> > --- a/Documentation/Doxyfile-common.in
> > +++ b/Documentation/Doxyfile-common.in
> > @@ -54,6 +54,9 @@ EXCLUDE_SYMBOLS        = libcamera::BoundMethodArgs \
> >  
> >  IMAGE_PATH             = "@TOP_SRCDIR@/Documentation/images"
> >  
> > +HTML_EXTRA_STYLESHEET  = "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome.css" \
> > +                         "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome-sidebar-only.css"
> > +
> >  GENERATE_LATEX         = NO
> >  
> >  MACRO_EXPANSION        = YES

Patch
diff mbox series 

diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
index c9527da03ed5..23a0e3626f9d 100644
--- a/Documentation/Doxyfile-common.in
+++ b/Documentation/Doxyfile-common.in
@@ -54,6 +54,9 @@  EXCLUDE_SYMBOLS        = libcamera::BoundMethodArgs \
 
 IMAGE_PATH             = "@TOP_SRCDIR@/Documentation/images"
 
+HTML_EXTRA_STYLESHEET  = "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome.css" \
+                         "@TOP_SRCDIR@/Documentation/doxygen-awesome-css/doxygen-awesome-sidebar-only.css"
+
 GENERATE_LATEX         = NO
 
 MACRO_EXPANSION        = YES