Re: Kernel docs: muddying the waters a bit

[Markus Heiser]

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--