Re: [TECH TOPIC] Kernel documentation

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

On Fri, 16 Jun 2023, Jonathan Corbet <corbet@lwn.net> wrote:
> The documentation discussion at past kernel summits has been lively, so
> I think we should do it again.  Some topics I would bring to a session
> this year would include:
>
> - The ongoing restructuring of the Documentation/ directory.  I've been
>   slowly moving the architecture docs into Documentation/arch/, but
>   would like to do more to reduce the clutter of the top-level directory
>   and make our documentation tree more closely resemble the organization
>   of the source.
>
> - Structure.  We continue to collect documents, but do little to tie
>   them together into a coherent whole.  Do we want to change that and,
>   if so, how?
>
> - Support for documentation work.  There is nobody in the community who
>   is paid to put any significant time into documentation, and it shows.
>   How can we fix that?
>
> - Infrastructure.  Sphinx brings a lot but is far from perfect; what can
>   we do to improve it?

It should be more feasible to build the documentation. Make it faster,
reduce the warnings.

Some ideas to make it faster:

- Bump the minimum Sphinx version requirement if it helps the speed. I
  don't think it needs to be as conservative as the compiler.

- Cache kernel-doc results per document. A bunch of .rst files use
  multiple kernel-doc directives for the same source file to better
  control the documentation order [1]. Each directive causes the same
  source to be parsed. (I'm not sure how bad the effect is though.)

- Simplify the rst output kernel-doc produces. For example, use rst
  native field lists for parameter and member descriptions instead of
  hand-crafting them. See [2]. Drop the "definition" part from
  structures, as nobody relies on it anyway. If necessary, add links to
  source instead.

- Default to Sphinx parallel build.

- Consider splitting the whole documentation to multiple smaller
  projects, and linking between them using intersphinx. (This may be a
  tall order.)

Some ideas to reduce warnings:

- W=1 already includes kernel-doc warnings for .c. In i915 we've added
  that to the regular build as well as a separate target to test
  headers, and use kernel-doc -Werror for development. Try to get more
  folks on board.

- Add more warning levels to kernel-doc similar to compilers, and reduce
  the default warnings. For example, I'm not sure it's necessary to warn
  about each undocumented parameter/member by default. That could be a
  verbose option. Bump up the warnings after we've fixed the more
  glaring issues.

- For more verbose checking without Sphinx, it should be possible to
  lint the rst produced by kernel-doc (originating from source), and
  check that as part of the build. But that's clearly W=2 stuff or on a
  subsystem/driver basis.

- Making the Sphinx build faster would also get more people on board
  fixing the warnings too.


BR,
Jani.



[1] git grep "^\.\. kernel-doc::" -- Documentation | sort | uniq -c | sort -rn | grep -v " 1 "
[2] https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists




>
> Other topics will certainly arise as well.
>
> jon
>

-- 
Jani Nikula, Intel Open Source Graphics Center