On Wed, 30 Mar 2022 19:07:24 +0200,
Mauro Carvalho Chehab wrote:
> Em Wed, 30 Mar 2022 23:59:05 +0900
> Akira Yokosawa <akiyks@xxxxxxxxx> escreveu:
>
>> Hi Mauro,
>>
>> On Wed, 30 Mar 2022 02:25:34 +0200,
>> Mauro Carvalho Chehab wrote:
>> [...]
>>> We need to verify both PDF and html generation, though, as I remember
>>> that some 4.x versions had/(have?) issues with the C domain and duplicate
>>> symbols detection.
>>
>> Can you elaborate on the issue you observed?
>> In which document did you see it?
>
> Sorry, it was on Sphinx 3.x, although the most complete fix got
> merged on 4.0, I guess. This patch is related to it:
>
> b34b86d7a418 ("docs: conf.py: fix c:function support with Sphinx 3.x")
>
> Basically, the Sphinx maintainer for the C domain rewrote the code,
> causing all references generated by kernel-doc to be broken, and
> almost all references at the media docs as well. Before the changes,
> there were just one domain for C code references, used for functions,
> structs, enums, etc. After the change, each one requires a different
> tag. The kerneldoc script has gained support for Sphinx version when
> such issue was addressed.
>
> Another consequence of such change is that you can't have more than
> one "read()" function inside the entire Kernel. While this makes
> sense on userspace, It doesn't at Kernelspace, as different subsystems
> may handle read/write/ioctl/... syscalls on their particular ways.
> So, building docs were causing warnings about duplicated symbols.
>
> There were some changes that went on 4.x to fix it, when
> ".. c:namespace::" got merged. I don't remember when it was added.
Thank you for the detailed explanation.
So I compared logs from "make SPHINXDIRS=driver-api htmldocs" with
Sphinx 2.4.4 and 4.5.0 on current docs-next.
There are 8 more lines in the log from 4.5.0 than from 2.4.4, give
or take minor format differences.
Here are those extra 8 lines (long lines are kept):
----
/wk/Documentation/driver-api/usb/usb.rst:967: WARNING: Duplicate C declaration, also defined at usb/gadget:775.
Declaration is '.. c:struct:: usb_string'.
/wk/Documentation/driver-api/miscellaneous:48: ./drivers/pwm/core.c:679: WARNING: Duplicate C declaration, also defined at miscellaneous:305.
Declaration is '.. c:function:: int pwm_capture (struct pwm_device *pwm, struct pwm_capture *result, unsigned long timeout)'.
/wk/Documentation/driver-api/surface_aggregator/client-api:25: ./drivers/platform/surface/aggregator/controller.c:1689: WARNING: Duplicate C declaration, also defined at surface_aggregator/client-api:105.
Declaration is '.. c:function:: int ssam_request_sync (struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)'.
/wk/Documentation/driver-api/80211/mac80211:109: ./include/net/mac80211.h:4811: WARNING: Duplicate C declaration, also defined at 80211/mac80211:1024.
Declaration is '.. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb)'.
----
So those "WARNING: Duplicate C declaration" messages are what you
mentioned earlier, aren't they?
I'm looking at Documentation/driver-api/usb/usb.rst:967 and
usb/gadget.rst:775, but can't figure out what is/are wrong.
How am I supposed to interpret those messages?
Are those line counts of intermediate files or some such?
>
>> Verification of generated HTML and PDF can be hard.
>>
>> Different Sphinx might generate slightly different .html or .tex
>> files with no visible effect in the final rendering. Hmm...
>
> That was not the case on that time. We had to stick to Sphinx up to
> version 2.4 for a couple of Kernel release cycles, in order to fix, as the
> changes weren't trivial.
>
>> Do you have an idea for automated regression testing?
>
> Except for doing periodic html and pdf builds and reporting build errors,
> no.
Ah, by "PDF and html generation", you meant build errors.
Now I understand what you said.
>
> For html, perhaps some regression testing could be done by using pandoc
> to convert html back into ReST (or to some other format) and compare if the
> output from the same source with different Sphinx versions are identical
> (or similar enough). On such case, I would get rid of using read the docs
> style, using the simplest possible one. That's easier said than done, though,
> as such conversion could produce errors due to problems on pandoc - or some
> minor differences - So, whomever would be running such tests would likely
> need to add something in order to handle similar but different outputs and
> exclude false-positives.
This sounds hard if not impossible...
Thanks, Akira
>
>>
>>>
>>> Also, it could be worth to check the build time with 2.4.4 and with
>>> whatever newer version we stick.
>>
>> I agree. I'll see what I can do.
>>
>> Thanks, Akira
>>
>>>
>>>> So I'll just fast-track this
>>>> patch in; dropping it into the stable updates probably makes sense too.
>>>
>>> Agreed.
>>>
>>> Thanks,
>>> Mauro
>
>
>
> Thanks,
> Mauro
