Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

[Jonathan Corbet]

On Tue, 16 Apr 2019 09:28:52 -0400
Mike Snitzer <snitzer@xxxxxxxxxx> wrote:

> Can you help me understand why this is the direction text based
> Documenation is taking in the Linux kernel?  All I see is markup, and
> escaping of characters, that is a chore to administer over time.

This is a discussion that was mostly resolved some years ago...

Classic Documentation/ is a jumbled collection of unorganized text files,
some of which contain highly useful information and others of which
haven't had much to offer since about 1996.  We are working to turn it
into an organized collection where, hopefully, some thought has actually
been given to the people who will be reading it.

The ReST conversion, in particular, allows us to link documents into a
larger structure, create indexes and cross references, and produce output
in formats like HTML and PDF.  It lets us present the documentation like
this:

	https://www.kernel.org/doc/html/latest/

Among other things, making the documentation more accessible in this way
makes it easier and more rewarding for developers to improve it, and I
believe we are seeing the results of that.  Linus called out the
documentation work in the 5.1-rc1 announcement, for example.

Nobody has complained about the maintenance burden of RST docs - so far as
I have heard, anyway.  Things do break occasionally, but problems in the
docs build almost always result from code changes that mess up the
kerneldoc comments rather than RST changes, and it's been that way for as
long as I've been paying attention.

Thanks,

jon