Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

From: Peter Zijlstra
Date: Wed Jun 19 2019 - 17:33:10 EST


On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> (c/c list cleaned)
>
> Em Wed, 19 Jun 2019 13:43:56 +0200
> Peter Zijlstra <peterz@xxxxxxxxxxxxx> escreveu:
>
> > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> >
> > > .../{ => driver-api}/atomic_bitops.rst | 2 -
> >
> > That's a .txt file, big fat NAK for making it an rst.
>
> Rst is a text file. This one is parsed properly by Sphinx without
> any changes.

In my tree it is a .txt file, I've not seen patches changing it. And I
disagree, rst is just as much 'a text file' as .c is.

> > > .../{ => driver-api}/futex-requeue-pi.rst | 2 -
> >
> > > .../{ => driver-api}/gcc-plugins.rst | 2 -
> >
> > > Documentation/{ => driver-api}/kprobes.rst | 2 -
> > > .../{ => driver-api}/percpu-rw-semaphore.rst | 2 -
> >
> > More NAK for rst conversion
>
> Again, those don't need any conversion. Those files already parse
> as-is by Sphinx, with no need for any change.

And yet, they're a .txt file in my tree. And I've not seen a rename,
just this move.

> The only change here is that, on patch 1/22, the files that
> aren't listed on an index file got a :orphan: added in order
> to make this explicit. This patch removes it.

I've no idea what :orphan: is. Text file don't have markup.

> > > Documentation/{ => driver-api}/pi-futex.rst | 2 -
> > > .../{ => driver-api}/preempt-locking.rst | 2 -
> >
> > > Documentation/{ => driver-api}/rbtree.rst | 2 -
> >
> > > .../{ => driver-api}/robust-futex-ABI.rst | 2 -
> > > .../{ => driver-api}/robust-futexes.rst | 2 -
> >
> > > .../{ => driver-api}/speculation.rst | 8 +--
> > > .../{ => driver-api}/static-keys.rst | 2 -
> >
> > > .../{ => driver-api}/this_cpu_ops.rst | 2 -
> >
> > > Documentation/locking/rt-mutex.rst | 2 +-
> >
> > NAK. None of the above have anything to do with driver-api.
>
> Ok. Where do you think they should sit instead? core-api?

Pretty much all of then are core-api I tihnk, with exception of the one
that are ABI, which have nothing to do with API. And i've no idea where
GCC plugins go, but it's definitely nothing to do with drivers.

Many of the futex ones are about the sys_futex user API, which
apparently we have Documentation/userspace-api/ for.

Why are you doing this if you've no clue what they're on about?

Just randomly moving files about isn't helpful.