Message-Id: <FE0A9B16-D835-4C4A-8149-320D74F36715@darmarit.de>
Date:	Fri, 6 May 2016 17:35:50 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jani Nikula <jani.nikula@...el.com>
Cc:	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Jonathan Corbet <corbet@....net>,
	Daniel Vetter <daniel@...ll.ch>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Grant Likely <grant.likely@...retlab.ca>,
	Dan Allen <dan@...ndevise.io>,
	Russel Winder <russel@...der.org.uk>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	Hans Verkuil <hverkuil@...all.nl>,
	LMML <linux-media@...r.kernel.org>,
	Graham Whaley <graham.whaley@...ux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit


Am 06.05.2016 um 17:06 schrieb Jani Nikula <jani.nikula@...el.com>:

> On Fri, 06 May 2016, Markus Heiser <markus.heiser@...marit.de> 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@....samsung.com>:

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

Powered by blists - more mailing lists