linux-next: build warnings after merge of the drivers-x86 tree

linux-next: build warnings after merge of the drivers-x86 tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 585 bytes --]

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Hans de Goede]

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

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 728 bytes --]

Hi all,

On Tue, 1 Mar 2022 20:16:59 +1100 Stephen Rothwell <sfr@canb.auug.org.au> 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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Hans de Goede]

Hi,

On 3/24/22 08:33, Stephen Rothwell wrote:
> Hi all,
> 
> On Tue, 1 Mar 2022 20:16:59 +1100 Stephen Rothwell <sfr@canb.auug.org.au> 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

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 1151 bytes --]

Hi Hans,

On Thu, 24 Mar 2022 08:39:19 +0100 Hans de Goede <hdegoede@redhat.com> 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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Hans de Goede]

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 <hdegoede@redhat.com> 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

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Hans de Goede]

<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 <hdegoede@redhat.com> 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

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 846 bytes --]

Hi Hans,

On Thu, 24 Mar 2022 14:04:28 +0100 Hans de Goede <hdegoede@redhat.com> 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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Mauro Carvalho Chehab]

Em Fri, 25 Mar 2022 08:55:22 +1100
Stephen Rothwell <sfr@canb.auug.org.au> escreveu:

> Hi Hans,
> 
> On Thu, 24 Mar 2022 14:04:28 +0100 Hans de Goede <hdegoede@redhat.com> 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

Re: linux-next: build warnings after merge of the drivers-x86 tree

[Mauro Carvalho Chehab]

Em Fri, 25 Mar 2022 06:27:35 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> escreveu:

> Em Fri, 25 Mar 2022 08:55:22 +1100
> Stephen Rothwell <sfr@canb.auug.org.au> escreveu:
> 
> > Hi Hans,
> > 
> > On Thu, 24 Mar 2022 14:04:28 +0100 Hans de Goede <hdegoede@redhat.com> 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

[PATCH] docs: kernel_abi.py: add sphinx build dependencies

[Mauro Carvalho Chehab]

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 <hdegoede@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---
 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