Re: [PATCH v2 00/24] Include linux ACPI docs into Sphinx TOC tree

Changbin Du
2019-04-09T16:17:12Z

On Fri, Apr 05, 2019 at 10:44:35AM +0800, Changbin Du wrote:
> + Bjorn
>
> On Wed, Apr 03, 2019 at 01:36:13PM -0600, Jonathan Corbet wrote:
> > On Tue, 2 Apr 2019 10:25:23 +0200
> > "Rafael J. Wysocki" <rafael@kernel.org> wrote:
> >
> > > There are ACPI-related documents currently in Documentation/acpi/ that
> > > don't clearly fall under either driver-api or admin-guide. For
> > > example, some of them describe various aspects of the ACPI support
> > > subsystem operation and some document expectations with respect to the
> > > ACPI tables provided by the firmware etc.
> > >
> > > Where would you recommend to put them after converting to .rst?
> >
> > OK, I've done some pondering on this. Maybe what we need is a new
> > top-level "hardware guide" book meant to hold information on how the
> > hardware works and what the kernel's expectations are. Architecture
> > information could maybe go there too. Would this make sense?
> >
> > If so, I could see a division like this:
> >
> > Hardware guide
> > acpi-lid
> > aml-debugger (or maybe driver api?)
> > debug (ditto)
> > DSD-properties-rules
> > gpio-properties
> > i2c-muxes
> >
> > Admin guide
> > cppc_sysfs
> > initrd_table_override
> >
> > Driver-API
> > enumeration
> > scan_handlers
> >
> > other:
> > dsdt-override: find another home for those five lines
> >
> Then, should we create dedicated sub-directories for these new charpters and
> move documents to coresspoding one? Now we have 'admin-guide' and all admin-guid
> docs are under it, otherwise we will have reference across different folders.
> For example, the 'admin-guide/index.rst' will have:
> ...
> ../acpi/osi
> ...
> Which seems not good.
>
Jonathan, what is your idea about the placement of doc files?

> > ...and so on. I've probably gotten at least one of those wrong, but that's
> > the idea.
> >
> > Of course, then it would be nice to better integrate those documents so
> > that they fit into a single coherent whole...a guy can dream...:)
> >
> I am not an adminstrator, so I don't know how adminstrators use this kernel
> documentation. But as a kernel developer, I prefer all related documents
> integrated into one charpter. Because I probably miss some useful sections
> if the documents are distributed into several charpters. And this is usually
> how a book is written (One charpter focus on one topic and has sub-sections
> such as overview, backgroud knowledge, implemenation details..),
> but a book mostly target on hypothetical readers...
>
After some considerarion, I have a new idea. Since the top charpter named as
*API* so non-API things is not suitable for this charpter. But can we just
rename it? For example, we can rename 'Kernel API documentation' to
'Subsystem-specifc documentation' which is similar to 'Architecture-specific documentation'?

Subsystem-specifc documentation
-------------------------------
.. toctree::
:maxdepth: 2

driver-api/index
core-api/index
media/index
networking/index
input/index
gpu/index
...

Architecture-specific documentation
-----------------------------------
.. toctree::
:maxdepth: 2

sh/index
x86/index
...

> > Thanks,
> >
> > jon
>
> --
> Cheers,
> Changbin Du

--
Cheers,
Changbin Du