Am 06.05.2016 um 17:06 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > 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. Could you post a link to a repo? / thanks There is no need for concurrency, let's work together on your repo. Within my POC I realized similar building processes we will need in the kernel sources ... where you have cascading configuration. A base configuration which fits for all common cases and (if needed) a *per-book* configuration. At the end, when it comes to generate pdf books/articles, man pages and e.g. texinfo files out of a sphinx-project you will need a build infrastructure like this. > 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. > > 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. > Ok, I agree with you in the fact that a additional "sphinx" folder is unrewarding. This means (e.g.) a migrated Documentation/DocBook/gpu book should placed in Documentation/gpu ... but don' try to merge all (Doc-)Books and .txt-files into one sphinx project! You will need on sphinx-project for each DocBook and one single sphinx-project where you collect the .txt to .rst migrated files. Am 06.05.2016 um 17:23 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>: > 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). Yes, it is named by the toolchain, but no one reads xml-files. Reading text files is common. > 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. I don't see a great potential of breakages ... if we place every book in a separated folder and have one project which collects the .txt files (see above). --Markus-- -- 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
