Em Fri, 6 May 2016 18:06:49 +0300 Jani Nikula <jani.nikula@xxxxxxxxx> escreveu: > On Fri, 06 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > > @Jonathan: what do you think? Should I prepare a patch > > with a basic reST (sphinx) build infrastructure, including > > > > * a folder for sphinx docs: > > > > ./Documentation/sphinx/ > > I'm already working on a patch series taking a different approach. I > don't think we should hide the documentation under an extra folder named > after a tool. Actually, I'm strongly opposed to that. > > Instead, we should place the Sphinx stuff directly under Documentation, > and have Sphinx recursively pick up all the *.rst files. We should > promote gradually switching to lightweight markup and integration of the > documents into one system. This process should be as little disruptive > as possible. We won't avoid the need of moving things among directories, as we have lots of stuff under DocBook/ dir (btw, named after the toolchain). Ok, if we put the .rst files at Documentation, we very likely reduce the number of renames, but we'll increase the Makefile complexity, and the risk of breakages. One alternative would be to put the sphinx stuff on a separate Makefile, but using multiple makefiles on a single dir is not standard at the Kernel. > If someone wants to convert a .txt document to .rst and get it processed > by Sphinx, it should be as simple as renaming the file, doing the > necessary edits, and adding it to a toctree. Imagine gradually > converting the files under, say, Documentation/kbuild. Why should the > .rst files be moved under another directory? They should stay alongside > the .txt files under the same directory. There's bound to be a lot of > people who'll never use Sphinx, and will expect to find the good old > plain text files (albeit with some markup) where they always were. Well, git will show the change as a rename, no matter if the directory name changes or not (except if we keep the rst files with .txt extension), but I agree with you that people will expect to see text files at Documentation, and most will just read it without caring to run Sphinx. -- Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
