[U-Boot] [PATCH RFC] doc: Replace DocBook with sphinx-based docs

[Mario Six]

Hi Tom,

On Mon, Jun 18, 2018 at 9:04 PM, Tom Rini <trini at konsulko.com> wrote:
> On Thu, Jun 14, 2018 at 10:44:53AM +0200, Mario Six wrote:
>
>> The Linux kernel moved to sphinx-based documentation and got rid of the
>> DocBook based documentation quite a while ago. Hence, the DocBook
>> documentation for U-Boot should be converted as well.
>>
>> To achieve this, import the necessary files from Linux v4.17-r6, and
>> convert the current DocBook documentation (three files altogether) to
>> sphinx/reStructuredText.
>>
>> For now, all old DocBook documentation was merged into a single
>> handbook, tentatively named "U-Boot Hacker Manual".
>>
>> For some source files, the documentation style was changed to comply
>> with kernel-doc; no functional changes were applied.
>>
>> Signed-off-by: Mario Six <mario.six at gdsys.cc>
>
> I like this idea, thanks for doing it.  While I wish more stuff was done
> for DocBook, and rST isn't my favorite style, it's worth I think
> strongly considering the switch to as I expect some of my own usage
> issues to be better by now or be addressed sooner rather than later as
> more people pick up the tools, find problems, and fix them.
>
> --
> Tom
>

First, thanks for the review! Should I send a proper patch, or are you going
to pull it in as-is?

While we're on the subject of documentation: I was looking for a place to
document the fact that sphinx-based docs are now available, and found myself
unsure of where to put that information, so I took a look at all the available
sources of documentation:

There's the wiki, the README, the docbook/sphinx documents (pretty much a
proxy for the embedded documentation in the source files), and the documents
located under doc/.

The wiki contains mostly "user documentation" (most of it in the manual), like
documentation for the command-line commands, and environment variables, but it
seems to be quite outdated in a lot of places. But there are also sections on
development methods, code quality or design principles, most of which seem to
be current.

The README contains "overview documentation" (for lack of a better term), is
aimed at both "users" and "developers", and is current in some, but outdated
in lots of other places (e.g. some of the mentioned boards don't even exist in
the sources anymore).

The docbook/sphinx documents, seem to be more "developer-centric", since it's
(for now) generated from the embedded API docs, which are, as far as I can
tell, pretty up-to-date if they exist. Also, infering from the "Bootloader
Hackers Manual" title from the docbook documents, there at least seemed to be
the idea to make some kind of developer manual in the past.

The documents under doc/ are a aggregation of documentation on specific
topics, like docs for special driver subsystems, or descriptions of the
operation of subsystems (like the DM overview), as well as guides for specific
technologies, and how-tos (like the DM-conversion guides). All with varying
degrees of currentness.

Hence, my two questions are as follows:

Where should which kind of documentation (aside from the API documentation,
obviously) go? Especially considerig the aspect that it's desireable that we
keep the duplication to a minimum (there seems to be at least some duplication
between the README and the manual from the wiki).

And: What kinds of documentation should exist? I think, e.g., a kind of
developer's manual that explains concepts, teaches best practices, and also
explains the rationales behind some decisions would be pretty useful (the
sphinx-based documentation would be suitable for this, I think), as would be a
manual that explains how to build, install and use U-Boot (which would be
pretty much the manual from the wiki, just updated).

Best regards,
Mario