Hi Tom,
On Mon, Jun 18, 2018 at 9:04 PM, Tom Rini trini@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@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