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

[Jani Nikula <jani.nikula@intel.com>]

On Sat, 18 Jun 2022, Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> The big missing feature on Sphinx itself is with regards to per-C-type
> domain. So, if we have one struct and one function both called "foo",
> the cross-references will be broken. This issue is known since Sphinx
> 3.1, and there are already patches fixing it since then (I remember
> testing them) but, up to today, the Sphinx upstream patches meant
> to fix it weren't applied yet (as far as I can tell).

https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#namespacing

Integrating that needs to be done carefully, though, to not make a mess
of it.

> One thing that probably be solved on a different way is to have
> a better solution for things like:
>
> 	Functions for feature 1
> 	=======================
>
> 	.. kernel-doc:: include/some_header.h
> 	   :doc: Feature 1
>
> 	.. kernel-doc:: include/some_header.h
> 	   :functions:
> 		func1
> 		func2
>
> 	Functions for feature 2
> 	=======================
>
> 	.. kernel-doc:: include/some_header.h
> 	   :doc: Feature 2
>
> 	.. kernel-doc:: include/some_header.h
> 	   :functions:
> 		func3
> 		func4

Yeah, currently that leads to parsing the header four times by
kernel-doc the script. The solution would be to finally convert the
script to a proper python Sphinx extension that can do caching. (This is
how it works in Hawkmoth, FWIW.)

> Perhaps we could change Kernel-doc in a way that doing just:
>
> 	.. kernel-doc:: include/some_header.h
>
> would be enough.

The order in nicely flowing documentation is not necessarily the same as
the order in nicely flowing source code. I expect it to be much more
acceptable to tweak the rst to achieve this than to do source code
rearrangement to generate nice documentation.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center