Re: [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Mon, 22 Jul 2019 13:11:51 +0100
Mark Brown <broonie@kernel.org> escreveu:

> On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:
> > While there's one file there with briefily describes the uAPI,
> > the documentation was written just like most subsystems: focused
> > on kernel developers. So, add it together with driver-api books.  
> 
> Please use subject lines matching the style for the subsystem.  This
> makes it easier for people to identify relevant patches.

Sure. Do you prefer this prefixed by:

	spi: docs:

Or with something else?

> >  Documentation/spi/{spidev => spidev.rst}      |  30 +++--  
> 
> This is clearly a userspace focused document rather than a kernel
> internal one.

True. What I've been doing so far is, for all drivers that I'm converting
with carries more than one documentation type (kABI, uABI and/or 
admin-guide) is to keep the directory as-is, adding them under
this section at Documentation/index.rst:

	Kernel API documentation
	------------------------

That's the case of media, input, hwmon, and so many other subsystems.

Yet, you're right: this implies that there will be some things
to be done, as the long-term documentation should be like:

	Documentation/admin-guide/{media, input, hwmon, spi, ...}
	Documentation/userspace-api/{media, input, hwmon, spi, ...}
	Documentation/driver-api/{media, input, hwmon, spi, ...}

Btw, if you look at spidev file, it contains stuff for both
userspace-api:

	"SPI devices have a limited userspace API, supporting basic half-duplex
	 read() and write() access to SPI slave devices.  Using ioctl() requests,"

And for admin-guide:

	"For a SPI device with chipselect C on bus B, you should see:

	    /dev/spidevB.C ... character special device, major number 153 with
		a dynamically chosen minor device number. "

So, if we're willing to move it, the best is to do on a separate patch
with would split its contents into two files: admin-guide/spi-devices.rst and 
userspace-api/spi-api.rst.

-

There are a couple of reasons why I opted for this strategy:

1) There are *lots* of docs that contain all 3 types of information
   on it on a single file.

2) On media, we use SPHINXDIRS to produce the media book from our
   devel tree:
	https://linuxtv.org/downloads/v4l-dvb-apis-new/index.html

   When documents are built with either PDF SPHINXDIRS, each subdir
   will be on a different book and all inter-book cross-references
   will break.
   
   For this to be fixed, we'll likely need to use something like
   intersphinx extension, but this would probably require a
   per-subsystem mapping (for example, saying that, for media, the
   site used to resolve broken cross references is linuxtv.org). 
   Maintaining it can be painful.

3) So far, I was unable to split even the media docs! Shame on
   me! The reason is that this is not an easy task.


One interesting example is at what we consider to be the media
uAPI book. It actually contains both sysadmin and uAPI documentation.

For example, at:

	Documentation/media/uapi/v4l/open.rst

You'll see that, while most things there belong to the admin
guide (device node descriptions, multiple opens, etc), it
mentions the Kernel userspace API - open(), read(), close() syscalls.

Splitting this file on two separate books won't be that easy.

Ideally, we should split what's there at media/uapi into admin-guide
and userspace-api, but this would mean *a lot* of efforts. Not sure
if it is worth the effort.


Thanks,
Mauro