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

[Tom Rini]

On Mon, Jun 25, 2018 at 02:02:22PM +0200, Mario Six wrote:

> 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?

A proper patch for just after 2018.07 please.

> 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).

Honestly, I don't know.  What I do see is that rST gives us easy HTML
output too and in turn that could be more easily updated / kept up to
date.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20180627/d567f185/attachment.sig>