Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

[Jani Nikula]

On Fri, 10 Jun 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
> Am 08.06.2016 um 21:49 schrieb Jonathan Corbet <corbet@xxxxxxx>:
>> But please,
>> at this point, let's build on Jani's work and go from there.  Things have
>> waited for long enough while we've gone around on this; I think what we
>> have is a good starting point.
>
> I'am willing to contribute, but take my POV: I have finished all
> including migration of **all** DocBook to reST, so why should I
> throw it all away?

Nobody is asking you to throw it away; we're asking you to rebase that
work, with some modifications, on top of docs-next, which now has my
work merged.

> are your friends. You will see that all requirements to get 
> productive are well done. Within the next days I will 
> add more features, which has been requested on the ML.

OTOH, if you do keep working on a baseline that no longer applies to
docs-next, you will be wasting your efforts.

> nevertheless which kind of implementation is used, the parsers are all
> exchangeable. There is only the user interface which has to be stable 
> and this is the ".. kernel-doc:" directive.
>
> I implemented a python version of the kernel-doc parser with an (python)
> API, so why should we fiddle with perl and pipes when implementing
> a ".. kernel-doc:" directive?

No matter how hacky the perl script seems, it has been used on the
kernel sources for nearly two decades. Sure, it has accumulated more
than a little cruft along the way, but also a lot of corner cases and
gotchas have been ironed out. I wouldn't dream of replacing that until
we've migrated a bunch of documents using it, and can confirm the
replacement produces the same output.

Also, there may still be users for the perl script outside of the Sphinx
pipeline. I'd like to make sure we don't end up having to maintain *two*
homebrew scripted C parsers before adding a new one.

>> Along these lines, I don't currently have a strong opinion on the
>> big-files vs. little-files question.  I *do*, however, like the idea of
>> trying to create one coherent kernel document rather than perpetuation our
>> current collection of independent book silos.  Initially it will certainly
>> look like the LDP-based books that people used to duct-tape together back
>> in the 90's, but it should improve over time.
>
> Placing all DocBooks in one huge sphinx-project does not scales well 
> and brings to additional dependencies. To solve this problem
> I use intersphinx and a index-page where all books are referred.

On the modifications, I'll repeat that I strongly object to maintaining
that arbitrary distinction between "books" and other files. We had that
with DocBook, and we'd be more than happy to get rid of it.

I object to adding a separate Sphinx project and duplicating a
configuration file per document. I object to splitting the documents too
much into small bits and pieces, for the reasons I explained in my
earlier email [1].

If someone wants to have separate projects with dedicated configuration
for special needs, they can add them. But I maintain that most documents
do not have that need, and everything is simpler without.

[1] http://mid.gmane.org/87wpm15q7q.fsf@xxxxxxxxx

> Read chapter "Getting started with reST" from [1].
> [1] https://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO

How about:

1) Write a file in rst, save it somewhere under Documentation.
2) Reference the file in Documentation/index.rst.
3) Be happy.

I'll hand it to you that you have more experience in Sphinx than I do,
but I like to think I know my fellow kernel developers better. The above
is what they want to hear. They don't want a single hurdle more.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center