Hi Jon, hi Daniel ! Am 25.01.2017 um 07:37 schrieb Daniel Vetter <daniel@xxxxxxxx>: >> Again, quick comments... >> >> - I would *much* rather evolve our existing Sphinx extension in the >> direction we want it to go than to just replace it wholesale. >> Replacement is the wrong approach for a few reasons, including the need >> to minimize change and preserve credit for Jani's work. Can we work on >> that basis, please? Sure. But I fear I haven't understood you right .... last post was: > Markus, would you consider sending out a new patch set for review? What I > would like to do see is something adding the new script for the Sphinx > toolchain, while leaving the DocBook build unchanged, using the old > script. We could then delete it once the last template file has moved > over. talking about DocBook and now I read ... >> Ideally at the time of merging, we would be able to build the docs with >> *either* kerneldoc. Now I'am totally confused ... it's no about you, but I do not understand you clearly ... can you help a conceptual man? > Seconded, I think renaming the extension string like this is just fairly > pointless busy-work. Hi Daniel, please help me, what did you mean with "renaming" the extension string and "busy-work"? There is a renaming of module's name but there should no work outside this patch ... > Kernel-doc isn't interacting perfectly with rst, but > now we already have a sizeable amount of stuff converted and going through > all that once more needs imo som really clear benefits. from authors POV nothing has changed. > I think bug-for-bug compatibility would be much better. Later on we could do > changes, on a change-by-change basis. Both sphinx-extensions (the one we have and the one in the series) are adapter to a "parser backend". 1. Documentation/sphinx/kerneldoc.py <--> scripts/kerneldoc -rst 2. Documentation/sphinx/rstKernelDoc.py <--> import module Documentation/sphinx/kernel_doc.py Maintain two adapters for the two backends is possible. But one adapter for two complete different backends .. is this what you mean? >> - I'll have to try it out to see how noisy it is. I'm not opposed to >> stricter checks; indeed, they could be a good thing. But we might want >> to have an option so we can cut back on the noise by default. As said, I'am willing to go communities way, it seems just a communication problem (on my side) to understand what this way would be. I try to sum what I guess ... e.g. to build output as usual with (1.) $ make htmldocs to build with the py-parser and its sphinx-extension (see 2. above):: $ USE_PY_PARSER=1 make htmldocs this should be easy and I can realize it in v2, but is this what you want? Please give me some more hints / Thanks a lot! --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
