On Wed, Nov 02, 2016 at 12:41:45PM +0200, Jani Nikula wrote: > On Wed, 02 Nov 2016, Luis de Bethencourt <luisbg@xxxxxxxxxxxxxxx> wrote: > > I also offer my help, let me know if you see anything I can do. > > Luis, Patrice, anyone else out there willing to help: here's a list of > stuff to do, off the top of my head. I'm sure Jon will amend this. > > 0) Some basics first > > Subscribe to linux-doc. Read it. > > Read https://lwn.net/Articles/692705/ and > https://lwn.net/Articles/704613/ if you haven't already. > > Figure out how to build the documentation. Read the part about writing > kernel documentation. Also at > http://static.lwn.net/kerneldoc/kernel-documentation.html. > > For most things under Documentation, you'll want to use the docs-next > branch of git://git.lwn.net/linux.git. That has the latest stuff. If you > use Linus' master, you'll be working on old stuff. > > For fixing kernel-doc source code comments, you'll need to use the > appropriate subsystem tree, see MAINTAINERS. > > In any case, most changes need to be sent to both linux-doc and the > relevant subsystem/driver mailing list. See MAINTAINERS and > scripts/get_maintainer.pl. > > Whatever you do, don't spend forever polishing it privately. Otherwise > someone might beat you to it, and effort will be wasted. Read the list, > maybe someone's already posted patches that just haven't been merged > yet. > > 1) Build documentation. Look at errors during build, fix them. > > Some of the issues come from source code comments via the kernel-doc > extension; those changes need to go through the appropriate subsystem, > not via the documentation tree. Watch out, some of the things may have > been fixed in the subsystem repo already. > > 2) Build documentation. Read the output, fix issues, improve the > language, improve the presentation. Ditto about source code comments. > > Personally, I think this is both very important and unfortunately > laborous, because this is mostly stuff that Sphinx won't warn about. > > 3) Look at documentation patches on linux-doc, review them, test them, > give feedback. > > 4) Convert DocBook templates under Documentation/DocBook to Sphinx. > > The conversion is actually the easy part; figuring out whether the > documentation is still relevant and where to stick it in the Sphinx > build is harder. Jon may have some vision on this, but personally I'd > like to obliterate DocBook first, and then figure out what to do with > the resulting converted rst documents. > > 5) Convert .txt files under Documentation to .rst. > > There are caveats here. Not everything needs to be converted. Some of > the stuff is obsolete, and converting might be wasted effort. Just > converting without updating to reflect current kernels is hazardous, > because the obsolete information will then be more accessible with the > converted documentation on the web. > > People like plain text, don't go overboard with rst markup. Use > discretion. 6) Go hunt for a subsystem/corner of the kernel you like which has already decent coverage with kernel-doc sourcecode comments. They start with /**. Then make sure there's suitable .rst templates in suitable places which pulls them in and ties them into our shiny new doc hierarchy. Mostly likely needs to be combined with steps 4) or 5) to really pull everything together for one substem. Then go back to step 3) and polish the result until it really shines ;-) > For both 4) and 5) I'd really like the seasoned kernel devs to actively > hand out stuff to willing new hands. Same for step 6) - you probably need to know a fair bit about that subsystem. Jon, should we put the above into some contribution howto in the kerneldocs itself? Would be even better if we'd put it as a colophon-thingy on every page (well, a link to the right section) to temp users/readers of our docs into contributing ... -Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
