Am 14.08.2016 um 20:09 schrieb Jonathan Corbet <corbet@xxxxxxx>: > On Sat, 13 Aug 2016 16:12:41 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > >> this series is a consolidation on Jon's docs-next branch. It merges the "sphinx >> sub-folders" patch [1] and the "parseheaders directive" patch [2] on top of >> Jon's docs-next. >> >> In sense of consolidation, it also includes: >> >> * doc-rst: add media/conf_nitpick.py >> >> Adds media/conf_nitpick.py from mchehab/docs-next [3]. >> >> * doc-rst: migrated media build to parseheaders directive > > OK, I have applied the first five of these, Thanks! > but stopped at parse-header. > At this point, I have a few requests. These are in approximate order of > decreasing importance, but they're all important, I think. > > - The new directive could really use some ... documentation. Preferably in > kernel-documentation.rst with the rest. What is parse-header, how does > it differ from kernel-doc, why might a kernel developer doing > documentation want (or not want) to use it? That's all pretty obscure > now. If we want others to jump onto this little bandwagon of ours, we > need to make sure it's all really clear. This could be answered by Mauro. > - Along those lines, is parse-header the right name for this thing? > "Parsing" isn't necessarily the goal of somebody who uses this directive, > right? They want to extract documentation information. Can we come up > with a better name? Mauro, what is your suggestion and how would we go on in this topic? > - Can we please try to get the coding style a bit more in line with both > kernel and Python community norms? Jonathan, we had this already, I gave you the links to "python community norms" and tools, please read/use them. * https://www.python.org/dev/peps/pep-0008/ * https://www.pylint.org/ Some of these norms might be unusual for C developers. > I suspect some people will get grumpy > if they see this code. In particular: > > - Please try to stick to the 80-column limit when possible. Python > makes that a bit harder than C does, and please don't put in > ridiculous line breaks that make the code worse. But sticking a bit > closer to the rule would be good. > > - The "#========================" lines around function/class > definition lines or other comments are not helpful, please avoid > them. Instead, placing a real comment with actual informative text > above the function/class would be a good thing. (I could live with > Python docstrings if you prefer, though I will confess I prefer > ordinary comments). > > - No commas at the beginning of continuation lines, please; that would > get you yelled at in C code. If you need to break a function call > (or whatever), please put the commas at the end of the line as is > done elsewhere. > > Sorry to poke at nits here, but we want others in the kernel community to > be able to look at this code, and that will be easier if we stick closer > to the usual rules. OK, if that's all you find, I will paint a eye candy picture for you. -- Markus -- -- 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
