Hi all,
After merging the drivers-x86 tree, today's linux-next build (htmldocs)
produced these warnings:
Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Unexpected indentation.
Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Definition list ends without a blank line; unexpected unindent.
Introduced by commit
2546c6000430 ("platform/x86: Add Intel Software Defined Silicon driver")
--
Cheers,
Stephen Rothwell
Hi,
On 3/1/22 10:16, Stephen Rothwell wrote:
> Hi all,
>
> After merging the drivers-x86 tree, today's linux-next build (htmldocs)
> produced these warnings:
>
> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Unexpected indentation.
> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Block quote ends without a blank line; unexpected unindent.
> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Definition list ends without a blank line; unexpected unindent.
>
> Introduced by commit
>
> 2546c6000430 ("platform/x86: Add Intel Software Defined Silicon driver")
Thank you for the report.
So I just did:
touch Documentation/ABI/testing/sysfs-driver-intel_sdsi
make htmldocs &> log
In a repo with drivers-x86/for-next checked out and checked the generated log files.
But I'm not seeing these WARNINGs.
Also 'find Documentation/output/ -name "*sdsi*"' does not output anything,
is there anything special (maybe some extra utilities?) which I need to also enable
building of htmldocs for the files in Documentation/ABI ?
Regards,
Hans
Hi,
On 3/24/22 08:33, Stephen Rothwell wrote:
> Hi all,
>
> On Tue, 1 Mar 2022 20:16:59 +1100 Stephen Rothwell <[email protected]> wrote:
>>
>> After merging the drivers-x86 tree, today's linux-next build (htmldocs)
>> produced these warnings:
>>
>> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Unexpected indentation.
>> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Block quote ends without a blank line; unexpected unindent.
>> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Definition list ends without a blank line; unexpected unindent.
>>
>> Introduced by commit
>>
>> 2546c6000430 ("platform/x86: Add Intel Software Defined Silicon driver")
>
> I am still seeing these warnings.
I replied to your original report on March 1st, but I never got a reply
to my reply:
"""
Thank you for the report.
So I just did:
touch Documentation/ABI/testing/sysfs-driver-intel_sdsi
make htmldocs &> log
In a repo with drivers-x86/for-next checked out and checked the generated log files.
But I'm not seeing these WARNINGs.
Also 'find Documentation/output/ -name "*sdsi*"' does not output anything,
is there anything special (maybe some extra utilities?) which I need to also enable
building of htmldocs for the files in Documentation/ABI ?
"""
If someone can let me know how to reproduce these warnings I would be happy
to fix them.
Regards,
Hans
Hi all,
On Tue, 1 Mar 2022 20:16:59 +1100 Stephen Rothwell <[email protected]> wrote:
>
> After merging the drivers-x86 tree, today's linux-next build (htmldocs)
> produced these warnings:
>
> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Unexpected indentation.
> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Block quote ends without a blank line; unexpected unindent.
> Documentation/ABI/testing/sysfs-driver-intel_sdsi:2: WARNING: Definition list ends without a blank line; unexpected unindent.
>
> Introduced by commit
>
> 2546c6000430 ("platform/x86: Add Intel Software Defined Silicon driver")
I am still seeing these warnings.
--
Cheers,
Stephen Rothwell
Hi Stephen,
On 3/24/22 12:22, Stephen Rothwell wrote:
> Hi Hans,
>
> On Thu, 24 Mar 2022 08:39:19 +0100 Hans de Goede <[email protected]> wrote:
>>
>> I replied to your original report on March 1st, but I never got a reply
>> to my reply:
>>
>> """
>> Thank you for the report.
>>
>> So I just did:
>>
>> touch Documentation/ABI/testing/sysfs-driver-intel_sdsi
>> make htmldocs &> log
>>
>> In a repo with drivers-x86/for-next checked out and checked the generated log files.
>> But I'm not seeing these WARNINGs.
>>
>> Also 'find Documentation/output/ -name "*sdsi*"' does not output anything,
>> is there anything special (maybe some extra utilities?) which I need to also enable
>> building of htmldocs for the files in Documentation/ABI ?
>> """
>>
>> If someone can let me know how to reproduce these warnings I would be happy
>> to fix them.
>
> Sorry about that. I am just doing what you are doing but with the
> whole of linux-next (which I don't think would make a difference). One
> possibility is that we are using different versions of the doco
> software.
>
> I am using Sphinx version 4.3.2 (using Python 3).
[hans@shalem ~]$ rpm -qf /usr/bin/sphinx-apidoc
python3-sphinx-4.4.0-1.fc36.noarch
So I did some digging and the trick for reproducing any ABI
related warnings is to touch the .rst file which has the
"kernel-abi" reST directive (1) for the ABI subdir you want
to regenerate the ABI docs for
this is
t
I doubt this makes a difference though. AFAIK the build process
for the files under Documentation/ABI is a bit different,
I think there is an extra pre-process step involved and maybe
I'm missing something needed for that step ?
Looking at Documentation/Makefile I did
Regards,
Hans
Hi Hans,
On Thu, 24 Mar 2022 14:04:28 +0100 Hans de Goede <[email protected]> wrote:
>
> So I did some digging and the trick for reproducing any ABI
> related warnings is to touch the .rst file which has the
> "kernel-abi" reST directive (1) for the ABI subdir you want
> to regenerate the ABI docs for.
>
> So in this case I did:
>
> touch Documentation/admin-guide/abi-testing.rst
> make htmldocs &> log
Looks like missing dependencies :-(
Thanks for persisting ad discovering this.
> And now I can see the warnings. I'll prepare a fix for this.
Excellent, thanks.
> Looking at Documentation/Makefile I also learned that you
> can also do this:
>
> scripts/get_abi.pl validate --dir Documentation/ABI
>
> Which results in a different set of warnings...
Wonderful :-(
--
Cheers,
Stephen Rothwell
<fat fingered send, sending an incomplete email, this is attempt 2>
Hi Stephen,
On 3/24/22 12:22, Stephen Rothwell wrote:
> Hi Hans,
>
> On Thu, 24 Mar 2022 08:39:19 +0100 Hans de Goede <[email protected]> wrote:
>>
>> I replied to your original report on March 1st, but I never got a reply
>> to my reply:
>>
>> """
>> Thank you for the report.
>>
>> So I just did:
>>
>> touch Documentation/ABI/testing/sysfs-driver-intel_sdsi
>> make htmldocs &> log
>>
>> In a repo with drivers-x86/for-next checked out and checked the generated log files.
>> But I'm not seeing these WARNINGs.
>>
>> Also 'find Documentation/output/ -name "*sdsi*"' does not output anything,
>> is there anything special (maybe some extra utilities?) which I need to also enable
>> building of htmldocs for the files in Documentation/ABI ?
>> """
>>
>> If someone can let me know how to reproduce these warnings I would be happy
>> to fix them.
>
> Sorry about that. I am just doing what you are doing but with the
> whole of linux-next (which I don't think would make a difference). One
> possibility is that we are using different versions of the doco
> software.
>
> I am using Sphinx version 4.3.2 (using Python 3).
[hans@shalem ~]$ rpm -qf /usr/bin/sphinx-apidoc
python3-sphinx-4.4.0-1.fc36.noarch
I doubt this makes a difference though.
So I did some digging and the trick for reproducing any ABI
related warnings is to touch the .rst file which has the
"kernel-abi" reST directive (1) for the ABI subdir you want
to regenerate the ABI docs for.
So in this case I did:
touch Documentation/admin-guide/abi-testing.rst
make htmldocs &> log
And now I can see the warnings. I'll prepare a fix for this.
Looking at Documentation/Makefile I also learned that you
can also do this:
scripts/get_abi.pl validate --dir Documentation/ABI
Which results in a different set of warnings...
Regards,
Hans
1) Implemented in Documentation/sphinx/kernel_abi.py
Em Fri, 25 Mar 2022 06:27:35 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
> Em Fri, 25 Mar 2022 08:55:22 +1100
> Stephen Rothwell <[email protected]> escreveu:
>
> > Hi Hans,
> >
> > On Thu, 24 Mar 2022 14:04:28 +0100 Hans de Goede <[email protected]> wrote:
> > >
> > > So I did some digging and the trick for reproducing any ABI
> > > related warnings is to touch the .rst file which has the
> > > "kernel-abi" reST directive (1) for the ABI subdir you want
> > > to regenerate the ABI docs for.
> > >
> > > So in this case I did:
> > >
> > > touch Documentation/admin-guide/abi-testing.rst
> > > make htmldocs &> log
> >
> > Looks like missing dependencies :-(
>
> Not sure if are there a way to fix this. See, Sphinx doesn't use Makefile
> dependencies, but, instead, it checks if the .rst file has changed or not.
> So, those tags that include contents from non-rst files, like the ABI ones
> and kernel-doc tags, are not considered by Sphinx when detecting the need
> to re-parse the .rst files that contain such tags.
It sounds that dependencies could added inside an extension using:
env.note_dependency()
kerneldoc.py already uses it. I'll try to add it also to the other
extensions there.
Thanks,
Mauro
Em Fri, 25 Mar 2022 08:55:22 +1100
Stephen Rothwell <[email protected]> escreveu:
> Hi Hans,
>
> On Thu, 24 Mar 2022 14:04:28 +0100 Hans de Goede <[email protected]> wrote:
> >
> > So I did some digging and the trick for reproducing any ABI
> > related warnings is to touch the .rst file which has the
> > "kernel-abi" reST directive (1) for the ABI subdir you want
> > to regenerate the ABI docs for.
> >
> > So in this case I did:
> >
> > touch Documentation/admin-guide/abi-testing.rst
> > make htmldocs &> log
>
> Looks like missing dependencies :-(
Not sure if are there a way to fix this. See, Sphinx doesn't use Makefile
dependencies, but, instead, it checks if the .rst file has changed or not.
So, those tags that include contents from non-rst files, like the ABI ones
and kernel-doc tags, are not considered by Sphinx when detecting the need
to re-parse the .rst files that contain such tags.
The safest way to ensure that Sphinx will process everything is running
is to run `make cleandocs` before building the documentation.
> Thanks for persisting ad discovering this.
>
> > And now I can see the warnings. I'll prepare a fix for this.
>
> Excellent, thanks.
>
> > Looking at Documentation/Makefile I also learned that you
> > can also do this:
> >
> > scripts/get_abi.pl validate --dir Documentation/ABI
No need to pass Documentation/ABI directory, as it assumes it per
default:
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/fault_ovuv is defined 2 times: Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856:14 Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865:0
Warning: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency is defined 2 times: Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865:12 Documentation/ABI/testing/sysfs-bus-iio:1943
Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times: Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92 Documentation/ABI/testing/sysfs-bus-iio:91
Warning: /sys/devices/system/cpu/cpuX/topology/core_id is defined 2 times: Documentation/ABI/testing/sysfs-devices-system-cpu:69 Documentation/ABI/stable/sysfs-devices-system-cpu:38
Btw, while here, you can also check if the new ABI definitions
are actually correct by running:
$ ./scripts/get_abi.pl undefined
On a system where the new ABI "What:" definitions can be found.
This command converts the What: field into a regular expression,
and then check if the entries under sysfs actually match the
location specified by the "What:" fields from the ABI files.
As there are currently many ones that are missing (or wrong), you
can limit the scope of the checks by adding --search-string <regex>,
like:
$ ./scripts/get_abi.pl undefined --search-string hugepage
/sys/kernel/mm/transparent_hugepage/defrag not found.
/sys/kernel/mm/hugepages/hugepages-2048kB/free_hugepages not found.
/sys/kernel/mm/hugepages/hugepages-1048576kB/demote_size not found.
...
/sys/kernel/mm/transparent_hugepage/khugepaged/full_scans not found.
> > Which results in a different set of warnings...
Such warnings are also reported at build time, when the ABI file is
processed - e. g. if you either touch the files containing the ABI
.rst files or if you do a make cleandocs before building the
documentation.
Thanks,
Mauro
Hi Hans,
On Thu, 24 Mar 2022 08:39:19 +0100 Hans de Goede <[email protected]> wrote:
>
> I replied to your original report on March 1st, but I never got a reply
> to my reply:
>
> """
> Thank you for the report.
>
> So I just did:
>
> touch Documentation/ABI/testing/sysfs-driver-intel_sdsi
> make htmldocs &> log
>
> In a repo with drivers-x86/for-next checked out and checked the generated log files.
> But I'm not seeing these WARNINGs.
>
> Also 'find Documentation/output/ -name "*sdsi*"' does not output anything,
> is there anything special (maybe some extra utilities?) which I need to also enable
> building of htmldocs for the files in Documentation/ABI ?
> """
>
> If someone can let me know how to reproduce these warnings I would be happy
> to fix them.
Sorry about that. I am just doing what you are doing but with the
whole of linux-next (which I don't think would make a difference). One
possibility is that we are using different versions of the doco
software.
I am using Sphinx version 4.3.2 (using Python 3).
[Adding those who do doco to cc for advise]
--
Cheers,
Stephen Rothwell
Ensure that Sphinx-build will handle the files parsed by
get_abi.pl as dependencies. This way, if they are touched,
the ABI output will be regenerated.
Reported-by: Hans de Goede <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/sphinx/kernel_abi.py | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 4392b3cb4020..efab9b14a9f5 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -128,6 +128,7 @@ class KernelCmd(Directive):
return out
def nestedParse(self, lines, fname):
+ env = self.state.document.settings.env
content = ViewList()
node = nodes.section()
@@ -154,6 +155,9 @@ class KernelCmd(Directive):
self.do_parse(content, node)
content = ViewList()
+ # Add the file to Sphinx build dependencies
+ env.note_dependency(os.path.abspath(f))
+
f = new_f
# sphinx counts lines from 0
--
2.35.1