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

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

Em Sun, 26 Jun 2022 08:55:24 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> escreveu:

> Em Sat, 25 Jun 2022 11:11:40 -0700
> Linus Torvalds <torvalds@linux-foundation.org> escreveu:
> 
> > On Sat, Jun 25, 2022 at 7:00 AM Jonathan Corbet <corbet@lwn.net> wrote:
> > >
> > > I said "some" - this was a proof-of-concept hack.  The complexity of
> > > their symbol lookup code is ... daunting ... and not something that gets
> > > fixed in one place.  More research is required...  
> > 
> > Note that at least for me, the issue with building docs isn't hugely
> > performance related.
> > 
> > Yes, yes, it would be good if it was faster. But..
> > 
> > The primary problems I see with building the docs (and thus checking
> > them, the same way I do an allmodconfig build test) is
> > 
> >  (a) it's insanely noisy, which makes and "check that it's ok" ENTIRELY USELESS.
> 
> When the environment is set for building docs, almost all output there
> are actually due to build errors/warnings that got introduced by patches
> touching documentation that were never build-tested.
> 
> There are 4 components that report errors during "make htmldocs". 
> 
> 1. Documentation cross-reference check. 
> 
> 	$ scripts/documentation-file-ref-check --warn
> 	Warning: Documentation/admin-guide/kernel-parameters.txt references a file that doesn't exist: Documentation/virt/kvm/amd-memory-encryption.rst
> 	Warning: Documentation/dev-tools/kunit/run_wrapper.rst references a file that doesn't exist: Documentation/dev-tools/kunit/non_uml.rst
> 	...
> 
> Those warnings are result of build-untested patches moving/renaming/removing 
> documentation without updating all documentation.
> 
> On almost all Kernel versions, I usually send a couple of patch series
> addressing them, but incomplete patches that forget about updating references
> keep being merged.
> 
> Without htmldocs build tests by patch authors, this is an endless job.

Just sent a patch series addressing the existing issues against
next-20220624:

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

With that, the number of warnings will be reduced to only 3:

	$ ./scripts/documentation-file-ref-check 
	Documentation/dev-tools/kunit/run_wrapper.rst: Documentation/dev-tools/kunit/non_uml.rst
	Documentation/devicetree/bindings/regulator/siliconmitus,sm5703-regulator.yaml: Documentation/devicetree/bindings/mfd/siliconmitus,sm5703.yaml
	drivers/acpi/device_pm.c: Documentation/firmware-guide/acpi/low-power-probe.rst

Those are actually useful for doc discussions, as they show one of
the issues we're currently having.

Sometimes, support for some functionality crosses multiple subsystems.
On such cases, part of the support may end being merged on a future
linux-next version - or even on a future Kernel version.

That seems to be the case of sm5703 support. The regulator bindings got
already merged, but the mfd ones weren't.

So, there's not much that could be done to fix
siliconmitus,sm5703-regulator.yaml broken reference to
mfd/siliconmitus,sm5703.yaml.

The same seems to apply to low-power-probe.rst: the patch adding
it was not merged yet at linux-next:

	https://lore.kernel.org/all/20210128232729.16064-3-sakari.ailus@linux.intel.com/

but the patch using it at drivers/acpi/device_pm.c was merged.

Regards,
Mauro