Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Mon, 27 Jun 2022 17:27:27 +0100
Mark Brown <broonie@kernel.org> escreveu:

> On Mon, Jun 27, 2022 at 03:28:40PM +0000, Liam Howlett wrote:
> > * Mauro Carvalho Chehab <mchehab@kernel.org> [220626 05:53]:  
> 
> > > Btw, once we fix the errors from the above checks, one of the things that 
> > > could be done in order to avoid noisy doc builds would be to run this 
> > > during normal Kernel build, if CONFIG_WERROR is set (and if .git is present
> > > at the source build dir):  
> 
> > > 	./scripts/documentation-file-ref-check --warn

Sent a patch series addressing those at linux-next:
	https://lore.kernel.org/linux-doc/cover.1656234456.git.mchehab@kernel.org/T/#t

> > > 	./scripts/get_abi.pl validate

I submited a patch fixing one such issue:
	https://lore.kernel.org/all/1e92337c1ef74f5eb9e1c1871e20b858b490d269.1656235926.git.mchehab@kernel.org/ 

and Jonathan Cameron submitted a series addressing those:

	https://lore.kernel.org/linux-iio/20220626165511.602202-1-jic23@kernel.org/T/#t 

> > > 	./scripts/kernel-doc --none $(git grep kernel-doc $(git ls-files Documentation/|grep -v kernel-doc.rst)|perl -ne 'print "$1\n" if (m/kernel-doc::\s*(\S+)/);'|sort|uniq)   

Sent a patch series addressing all of those, also against linux-next:

	https://lore.kernel.org/linux-doc/cover.1656409369.git.mchehab@kernel.org/T/#t

next-20220627 has currently:
	32 cross broken docs cross reference warnings;
	 4 duplicated ABI symbols;
	60 kernel-doc warnings.

After having those three series applied, the 3 above commands would
produce just 3 warnings:

	Warning: Documentation/dev-tools/kunit/run_wrapper.rst references a file that doesn't exist: Documentation/dev-tools/kunit/non_uml.rst
	Warning: Documentation/devicetree/bindings/regulator/siliconmitus,sm5703-regulator.yaml references a file that doesn't exist: Documentation/devicetree/bindings/mfd/siliconmitus,sm5703.yaml
	Warning: drivers/acpi/device_pm.c references a file that doesn't exist: Documentation/firmware-guide/acpi/low-power-probe.rst

Those 3 warnings depend on non-merged documents.

After those ~100 warnings that can be quickly checked with the 3 above
command lines in a couple of seconds, there are the Sphinx errors.
Reducing the build time (currently at 10 mins order) to something more
palatable could help having more people checking them before submitting
patches and waiting for 0day results.

> That last one is quite the command line...

True. Yet, placing it at docs/Makefile for the "make all" target should be 
trivial and will hopefully make more Kernel developers to check for some of 
the documentation issues. 

The other two are already called, depending on some config vars:

	# Check for broken documentation file references
	ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
	$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
	endif

	# Check for broken ABI files
	ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
	$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
	endif

But they don't currently stop the build if CONFIG_WERROR is enabled.


> 
> > > aborting the build on such warnings.  
> 
> > > On my notebook (i5-10210U), the above takes ~8 seconds to run. So, it 
> > > won't make much difference at the build time, and doing that would have
> > > avoided ~100 warnings during htmldocs build against current linux-next.  
> 
> > Couldn't we add this to the build bots and ask the authors to fix the
> > commits?  
> 
> There's reports for at least some of this for -next already, at least
> for newly introduced warnings.  If we could get 0day or something else
> that picks stuff off the lists that would help a lot I think, as would
> getting it into the bots that people who like to fix up warnings tend to
> be using.

Yes, newly-introduced warnings are monitored there, but still patches
adding new warnings keep being merged, requiring extra periodic janitorial
work in order to reduce the build noise that would otherwise increase
with time.

Regards,
Mauro