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 <[email protected]> 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 <[email protected]> > > > > 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
signature.asc
Description: PGP signature
_______________________________________________ U-Boot mailing list [email protected] https://lists.denx.de/listinfo/u-boot
