ksummit.lists.linux.dev archive mirror
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be
Date: Sat, 18 Jun 2022 09:24:47 +0100	[thread overview]
Message-ID: <20220618092447.5ebed314@sal.lan> (raw)
Message-ID: <20220618082447.t7QWk05AIHhP7EYEEecnzekIsZ-TYYKeaFoZJDFu1tE@z> (raw)
In-Reply-To: <87sfo3nh3t.fsf@meer.lwn.net>

Hi John,

Em Fri, 17 Jun 2022 14:57:10 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> The development community has put a lot of work into the kernel's
> documentation directory in recent years, with visible results. But the
> kernel's documentation still falls far short of the standard set by many
> other projects, and there is a great deal of "tribal knowledge" in our
> community that is not set down. I'd like to look at the successes and
> failures of the work so far, but intent to focus on a discussion of what
> our documentation should be and what we can do to get it there.
> Questions to discuss include:
>  - Bringing an coherent overall structure to Documentation/

Fully agreed. We dedicated a lot of resources on the past years to
convert documentation to ReST and on kernel-doc, but not so much
on placing the topics at the right order.

There are a huge amount of such documentation that describe border cases,
or have just kernel-doc tags without any (or very small) descriptions.
Kernel-doc markups are important, as they help to keep the documentation
updated, but explaining subsystem's principles is equally important, as
it can save a lot of time from maintainers if the contributors are aware
on how and why the subsystem's kAPIs were organized the way it is.

We should imagine documentation as if this is a series of books describing
every aspect of the kernel. So, I would expect it to be organized with
some structure that would place the topics on some order that would make
easier for people to read, being either new contributors or experienced
developers that need to touch other parts of the Kernel that are out of
his past experiences.

For instance to the kAPI documentation, I would expect something like:

	- How to contribute / Submission process;
	- An introductory chapter that would describe the most used
	  components that all developers need to know, like:

		- how to write a driver;
		- fs principles;
		- scheduler principles;
		- mm most used functions (kmalloc & friends);
		- wait queues;
		- kernel threads;
		- softirqs;
		- arch-dependent items to consider (like bit order), weak
		  memory model, etc;
		- ...

	  IMO, we could take a look at the index of some already-existing 
	  books like LDD 3, Linux Kernel Development and others in order to
	  get a rough idea about the items to be covered there.
	- Bus-related subsystems (USB, PCI, I2C, ...);
	- Then, place per-subsystem's documentation, all having their
	  texts explaining basic principles.

IMO, we should write an index file and a couple of new ReST files with an
skeleton for the above, and then ask people to help filling the blanks.

>  - Making it easier for developers to improve the documentation.

A well-prepared skeleton would make life easier. From time to time, we
have discussions and patches shifting documentation between different

>  - What we would like from Sphinx and what we can do to make it happen

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).

Another problem is with regards to the documentation's build time.

One feature we're not using yet is intersphinx. Right now, we can
build parts of the documentation with:

	make SPHINXDIRS="foo" htmldocs

But, if "foo" have cross-references to "bar", the build will produce
warnings and the documentation's cross-references to "bar" won't work.

Properly setting interphinx would allow this to work, as such references
would point, instead, to some remote place (like kernel.org).

This could be used to help improving the documentation's build time 
during doc development.

Also, I would love to have a good way to just produce html (and pdf) from
the documents I'm actually working with. The way I do it right now is
that I create a "Documentation/foo" directory, adding there just the docs
I'm currently working with, placing them on a fake index.rst file.

This way, I can build them really fast, without needing to rebuild
everything at the same book. Perhaps something like that could be 
automated - or Sphinx itself could support something like:

	make htmldocs SPHINXFILES="foo.rst bar.rst"

>  - Making the docs build system less ugly and more maintainable

I guess shifting the minimal Sphinx version would help to remove some
bad things there.

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 for feature 2

	.. kernel-doc:: include/some_header.h
	   :doc: Feature 2

	.. kernel-doc:: include/some_header.h

Perhaps we could change Kernel-doc in a way that doing just:

	.. kernel-doc:: include/some_header.h

would be enough.

> - Integrating rustdoc documentation

Won't comment much about that, as never touched any of those.

Life would be a lot easier on this side if rustdoc could
support ReST.


  parent reply	other threads:[~2022-06-18  8:24 UTC|newest]

Thread overview: 40+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-06-17 20:57 [TECH TOPIC] What kernel documentation could be Jonathan Corbet
2022-06-17 20:57 ` [Ksummit-discuss] " Jonathan Corbet
2022-06-17 21:48 ` Laurent Pinchart
2022-06-17 21:48   ` Laurent Pinchart
2022-06-27 15:18   ` Jonathan Corbet
2022-06-18  8:24 ` Mauro Carvalho Chehab [this message]
2022-06-18  8:24   ` Mauro Carvalho Chehab
2022-06-18 11:03   ` Miguel Ojeda
2022-06-18 11:16     ` Mauro Carvalho Chehab
2022-06-18 11:16       ` Mauro Carvalho Chehab
2022-06-18 14:37       ` Miguel Ojeda
2022-06-23  9:18   ` Jani Nikula
2022-06-23  9:57     ` Mauro Carvalho Chehab
2022-06-23 10:30       ` Jani Nikula
2022-06-23 13:40       ` Jonathan Corbet
2022-06-24  7:33         ` Mauro Carvalho Chehab
2022-06-24 16:37           ` Markus Heiser
2022-06-27 15:27             ` Jonathan Corbet
2022-06-27 15:31               ` Christoph Hellwig
2022-06-28  7:43               ` Mauro Carvalho Chehab
2022-06-28  7:57                 ` Geert Uytterhoeven
2022-06-28 11:01                   ` Mauro Carvalho Chehab
2022-07-02 12:43                     ` Stephen Rothwell
2022-06-24 22:57           ` Jonathan Corbet
2022-06-25  9:10             ` Mauro Carvalho Chehab
2022-06-25 14:00               ` Jonathan Corbet
2022-06-25 18:11                 ` Linus Torvalds
2022-06-26  7:55                   ` Mauro Carvalho Chehab
2022-06-26  9:26                     ` Mauro Carvalho Chehab
2022-06-26  9:53                     ` Mauro Carvalho Chehab
2022-06-27 15:28                       ` Liam Howlett
2022-06-27 15:54                         ` Christian Brauner
2022-06-27 16:27                         ` Mark Brown
2022-06-28 10:53                           ` Mauro Carvalho Chehab
2022-06-28 16:13                         ` Luck, Tony
2022-06-27 15:34                   ` Jonathan Corbet
2022-06-27 17:07                     ` Linus Torvalds
2022-07-02 10:52                   ` Mauro Carvalho Chehab
2022-06-25 17:43 ` Steven Rostedt
2022-06-25 17:48   ` Laurent Pinchart

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220618092447.5ebed314@sal.lan \
    --to=mchehab@kernel.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).