[v2,04/10] Documentation: Enable doxygen-awesome-css
diff mbox series

Message ID 20250911230115.25335-5-laurent.pinchart@ideasonboard.com
State Superseded
Headers show
Series
  • Documentation theming update
Related show

Commit Message

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

Include doxygen-awesome-css in the doxygen config.

Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
---
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 | 5 +++++
 1 file changed, 5 insertions(+)

Comments

Barnabás Pőcze Sept. 12, 2025, 11 a.m. UTC | #1 
2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> Include doxygen-awesome-css in the doxygen config.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> ---
> 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 | 5 +++++
>   1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> index c9527da03ed5..2844d215bc60 100644
> --- a/Documentation/Doxyfile-common.in
> +++ b/Documentation/Doxyfile-common.in
> @@ -54,6 +54,11 @@ 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"
> +HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5

Unfortunately while testing locally I ran into a compatibility issue: https://github.com/jothepro/doxygen-awesome-css/issues/185
Example: https://ibb.co/d0GQWQ1m I suppose the trick is not to update doxygen until is
addressed in some capacity...


Regards,
Barnabás Pőcze

> +
> +GENERATE_TREEVIEW      = YES
>   GENERATE_LATEX         = NO
>   
>   MACRO_EXPANSION        = YES
Laurent Pinchart Sept. 12, 2025, 5:10 p.m. UTC | #2 
On Fri, Sep 12, 2025 at 01:00:16PM +0200, Barnabás Pőcze wrote:
> 2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
> > From: Stefan Klug <stefan.klug@ideasonboard.com>
> > 
> > Include doxygen-awesome-css in the doxygen config.
> > 
> > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> > ---
> > 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 | 5 +++++
> >   1 file changed, 5 insertions(+)
> > 
> > diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> > index c9527da03ed5..2844d215bc60 100644
> > --- a/Documentation/Doxyfile-common.in
> > +++ b/Documentation/Doxyfile-common.in
> > @@ -54,6 +54,11 @@ 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"
> > +HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
> 
> Unfortunately while testing locally I ran into a compatibility issue: https://github.com/jothepro/doxygen-awesome-css/issues/185
> Example: https://ibb.co/d0GQWQ1m I suppose the trick is not to update doxygen until is
> addressed in some capacity...

The bug report indicates an issue with dark mode, while here we enable
light mode. Is there an issue with light mode too ? Or is there a
problem only for people who wants to switch to dark mode, overriding the
libcamera default configuration ?

> > +
> > +GENERATE_TREEVIEW      = YES
> >   GENERATE_LATEX         = NO
> >   
> >   MACRO_EXPANSION        = YES
>
Barnabás Pőcze Sept. 15, 2025, 8:23 a.m. UTC | #3 
Hi

2025. 09. 12. 19:10 keltezéssel, Laurent Pinchart írta:
> On Fri, Sep 12, 2025 at 01:00:16PM +0200, Barnabás Pőcze wrote:
>> 2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
>>> From: Stefan Klug <stefan.klug@ideasonboard.com>
>>>
>>> Include doxygen-awesome-css in the doxygen config.
>>>
>>> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
>>> ---
>>> 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 | 5 +++++
>>>    1 file changed, 5 insertions(+)
>>>
>>> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
>>> index c9527da03ed5..2844d215bc60 100644
>>> --- a/Documentation/Doxyfile-common.in
>>> +++ b/Documentation/Doxyfile-common.in
>>> @@ -54,6 +54,11 @@ 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"
>>> +HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
>>
>> Unfortunately while testing locally I ran into a compatibility issue: https://github.com/jothepro/doxygen-awesome-css/issues/185
>> Example: https://ibb.co/d0GQWQ1m I suppose the trick is not to update doxygen until is
>> addressed in some capacity...
> 
> The bug report indicates an issue with dark mode, while here we enable
> light mode. Is there an issue with light mode too ? Or is there a
> problem only for people who wants to switch to dark mode, overriding the
> libcamera default configuration ?

But the documentation appears to me with a dark theme "out of the box" (even if `HTML_COLORSTYLE = LIGHT`).
It seems to me that that option has no effect if doxygen-awesome-css is used. And in that case the
issue I described is present, at least as long as doxygen 1.14 (or newer?) is used.


Regards,
Barnabás Pőcze

> 
>>> +
>>> +GENERATE_TREEVIEW      = YES
>>>    GENERATE_LATEX         = NO
>>>    
>>>    MACRO_EXPANSION        = YES
>>
>
Laurent Pinchart Sept. 15, 2025, 8:47 a.m. UTC | #4 
On Mon, Sep 15, 2025 at 10:23:05AM +0200, Barnabás Pőcze wrote:
> 2025. 09. 12. 19:10 keltezéssel, Laurent Pinchart írta:
> > On Fri, Sep 12, 2025 at 01:00:16PM +0200, Barnabás Pőcze wrote:
> >> 2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
> >>> From: Stefan Klug <stefan.klug@ideasonboard.com>
> >>>
> >>> Include doxygen-awesome-css in the doxygen config.
> >>>
> >>> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> >>> ---
> >>> 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 | 5 +++++
> >>>    1 file changed, 5 insertions(+)
> >>>
> >>> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> >>> index c9527da03ed5..2844d215bc60 100644
> >>> --- a/Documentation/Doxyfile-common.in
> >>> +++ b/Documentation/Doxyfile-common.in
> >>> @@ -54,6 +54,11 @@ 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"
> >>> +HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
> >>
> >> Unfortunately while testing locally I ran into a compatibility issue: https://github.com/jothepro/doxygen-awesome-css/issues/185
> >> Example: https://ibb.co/d0GQWQ1m I suppose the trick is not to update doxygen until is
> >> addressed in some capacity...
> > 
> > The bug report indicates an issue with dark mode, while here we enable
> > light mode. Is there an issue with light mode too ? Or is there a
> > problem only for people who wants to switch to dark mode, overriding the
> > libcamera default configuration ?
> 
> But the documentation appears to me with a dark theme "out of the box" (even if `HTML_COLORSTYLE = LIGHT`).

Ah I hadn't understood that. For me it appears in light mode. I'm using
doxygen 1.13.2.

> It seems to me that that option has no effect if doxygen-awesome-css is used. And in that case the
> issue I described is present, at least as long as doxygen 1.14 (or newer?) is used.

I'll give 1.14 a try.

> >>> +
> >>> +GENERATE_TREEVIEW      = YES
> >>>    GENERATE_LATEX         = NO
> >>>    
> >>>    MACRO_EXPANSION        = YES
Barnabás Pőcze Sept. 15, 2025, 8:50 a.m. UTC | #5 
2025. 09. 15. 10:47 keltezéssel, Laurent Pinchart írta:
> On Mon, Sep 15, 2025 at 10:23:05AM +0200, Barnabás Pőcze wrote:
>> 2025. 09. 12. 19:10 keltezéssel, Laurent Pinchart írta:
>>> On Fri, Sep 12, 2025 at 01:00:16PM +0200, Barnabás Pőcze wrote:
>>>> 2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
>>>>> From: Stefan Klug <stefan.klug@ideasonboard.com>
>>>>>
>>>>> Include doxygen-awesome-css in the doxygen config.
>>>>>
>>>>> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
>>>>> ---
>>>>> 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 | 5 +++++
>>>>>     1 file changed, 5 insertions(+)
>>>>>
>>>>> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
>>>>> index c9527da03ed5..2844d215bc60 100644
>>>>> --- a/Documentation/Doxyfile-common.in
>>>>> +++ b/Documentation/Doxyfile-common.in
>>>>> @@ -54,6 +54,11 @@ 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"
>>>>> +HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
>>>>
>>>> Unfortunately while testing locally I ran into a compatibility issue: https://github.com/jothepro/doxygen-awesome-css/issues/185
>>>> Example: https://ibb.co/d0GQWQ1m I suppose the trick is not to update doxygen until is
>>>> addressed in some capacity...
>>>
>>> The bug report indicates an issue with dark mode, while here we enable
>>> light mode. Is there an issue with light mode too ? Or is there a
>>> problem only for people who wants to switch to dark mode, overriding the
>>> libcamera default configuration ?
>>
>> But the documentation appears to me with a dark theme "out of the box" (even if `HTML_COLORSTYLE = LIGHT`).
> 
> Ah I hadn't understood that. For me it appears in light mode. I'm using
> doxygen 1.13.2.

I forgot to mention that my browser/system preference is set to "dark".


> 
>> It seems to me that that option has no effect if doxygen-awesome-css is used. And in that case the
>> issue I described is present, at least as long as doxygen 1.14 (or newer?) is used.
> 
> I'll give 1.14 a try.
> 
>>>>> +
>>>>> +GENERATE_TREEVIEW      = YES
>>>>>     GENERATE_LATEX         = NO
>>>>>     
>>>>>     MACRO_EXPANSION        = YES
>
Laurent Pinchart Sept. 15, 2025, 2:17 p.m. UTC | #6 
On Mon, Sep 15, 2025 at 10:50:33AM +0200, Barnabás Pőcze wrote:
> 2025. 09. 15. 10:47 keltezéssel, Laurent Pinchart írta:
> > On Mon, Sep 15, 2025 at 10:23:05AM +0200, Barnabás Pőcze wrote:
> >> 2025. 09. 12. 19:10 keltezéssel, Laurent Pinchart írta:
> >>> On Fri, Sep 12, 2025 at 01:00:16PM +0200, Barnabás Pőcze wrote:
> >>>> 2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
> >>>>> From: Stefan Klug <stefan.klug@ideasonboard.com>
> >>>>>
> >>>>> Include doxygen-awesome-css in the doxygen config.
> >>>>>
> >>>>> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> >>>>> ---
> >>>>> 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 | 5 +++++
> >>>>>     1 file changed, 5 insertions(+)
> >>>>>
> >>>>> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> >>>>> index c9527da03ed5..2844d215bc60 100644
> >>>>> --- a/Documentation/Doxyfile-common.in
> >>>>> +++ b/Documentation/Doxyfile-common.in
> >>>>> @@ -54,6 +54,11 @@ 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"
> >>>>> +HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5

I was wondering why light mode was behaving like auto-light mode. It
seems that doxygen will generate .css files depending on the
HTML_COLORSTYLE option. When set to light, the .css will hardcode light
mode, while with auto-light it will make it dynamic. As
doxygen-awesome.css is a static file, it can't do the same. It instead
implements auto mode, and allows disabling auto-light mode by setting
class="light-mode" in the html element in the header template (see
https://github.com/jothepro/doxygen-awesome-css/blob/main/docs/tricks.md#disable-dark-mode-tricks-darkmode).

> >>>> Unfortunately while testing locally I ran into a compatibility issue: https://github.com/jothepro/doxygen-awesome-css/issues/185
> >>>> Example: https://ibb.co/d0GQWQ1m I suppose the trick is not to update doxygen until is
> >>>> addressed in some capacity...
> >>>
> >>> The bug report indicates an issue with dark mode, while here we enable
> >>> light mode. Is there an issue with light mode too ? Or is there a
> >>> problem only for people who wants to switch to dark mode, overriding the
> >>> libcamera default configuration ?
> >>
> >> But the documentation appears to me with a dark theme "out of the box" (even if `HTML_COLORSTYLE = LIGHT`).
> > 
> > Ah I hadn't understood that. For me it appears in light mode. I'm using
> > doxygen 1.13.2.
> 
> I forgot to mention that my browser/system preference is set to "dark".

Ah that explains it.

I've tried doxygen 1.14 and I can reproduce the problem. Even in light
mode the page isn't rendered as with doxygen 1.13.2.

This is an issue in doxygen-awesome-css, they will have to update to
newer doxygen versions. I think we could ignore the issue for now and
update our copy of the .css files once the problem gets fixed upstream.

Note that in dark mode the "light mode leakage" is worse in
HTML_COLORSTYLE is set to LIGHT, compared to AUTO_LIGHT (which is the
default value). I think we're better off not setting HTML_COLORSTYLE.
Even if listed as required since Doxygen 1.9.5, I don't see why that's
required. I've tested Doxygen 1.9.5, thinking that the requirement may
have disappeared in newer versions, but that doesn't seem to be the
case.

> >> It seems to me that that option has no effect if doxygen-awesome-css is used. And in that case the
> >> issue I described is present, at least as long as doxygen 1.14 (or newer?) is used.
> > 
> > I'll give 1.14 a try.
> > 
> >>>>> +
> >>>>> +GENERATE_TREEVIEW      = YES
> >>>>>     GENERATE_LATEX         = NO
> >>>>>     
> >>>>>     MACRO_EXPANSION        = YES

Patch
diff mbox series 

diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
index c9527da03ed5..2844d215bc60 100644
--- a/Documentation/Doxyfile-common.in
+++ b/Documentation/Doxyfile-common.in
@@ -54,6 +54,11 @@  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"
+HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
+
+GENERATE_TREEVIEW      = YES
 GENERATE_LATEX         = NO
 
 MACRO_EXPANSION        = YES