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

[Jonathan Corbet <corbet@lwn.net>]

Markus Heiser <markus.heiser@darmarit.de> writes:

> IMO It is unnecessary that the build-chain must run on all
> platforms and with all distributions.
>
> Who observes the Sphinx-doc & docutils development since (>15)
> years is aware that with various (old) Sphinx-doc & docutils
> versions no stable results can be produced, not without
> complicating the build-chain.  And this is exactly the situation
> we are facing today.
>
> The build chain of documentation has nothing to do with kernel
> development (at least in my opinion) and should be decoupled from it:
> maintaining one defined build environment is enough work ... this
> becomes especially clear if you (as Jani recommends) rely more on
> sphinx-modules and widely used tools.

The counterargument to this is that we want as many developers as
possible to be able to build the docs and contribute to them.  We can't
complain that developers have broken the docs build if we don't do what
we can to help them do the build themselves.

One of our longstanding contributors is on Sphinx 1.8.5:

  https://lwn.net/ml/linux-doc/4c403239-3c71-4ab9-2168-f7e9d77008b2%40infradead.org/

I would like to narrow our range of supported versions, but I really
don't want to cut people out.

The real question, perhaps, is whether requiring people to set up a
virtualenv to run a supported version would be too much.  It's something
I worry about.

> Another point on which I now have a clear view are the regular
> expressions: no one likes them (me too), but I can't think of a
> general solution (parser) given the number of requirements for
> parsing source code we have.

I fear you're right.  There are nice C parsers for Python, but they
don't work at the level we need; we need the comments, unexpanded
macros, etc.

That said, the regex expression in kernel-doc is out of hand, with no
documentation, lots of duplication, etc.

> I would like to support the kernel community again, but at the
> moment I have difficulties to follow the many exceptions. I would
> be happy if you keep me in CC .. may be I find my place again
> back in the kernel-doc development :-)

We would be glad to have you back.

Remember that the reason I was hesitant to take your kernel-doc rewrite
at the time was that we were already thrashing too many things and I
wanted to hold at least one piece stable.  Hopefully we're past that
phase now...:)

Thanks,

jon