Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next

[Markus Heiser]

Am 29.06.2016 um 15:15 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:

> On Wed, 29 Jun 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
>> Am 28.06.2016 um 21:05 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:
>>> Perhaps you misunderstood, I don't know. When we ask you to rebase your
>>> work on something, in this case docs-next, it generally means, accept
>>> what is there, and iteratively build and extend upon it, *not* rip out
>>> and rewrite everything from scratch.
>>> 
>>> Several people have spent a non-insignificant amount of time to review
>>> and polish what is in docs-next currently. We've converted gpu
>>> documentation on top, in drm-next, and set up autobuilders for it. We've
>>> ironed out python2 vs python3 issues. We've fixed kernel-doc comments
>>> here and there. Written documentation for the whole thing. Generally
>>> tested the stuff in various environments. Etc, etc. That is the baseline
>>> now, and it should be improved on iteratively, not destructively. That's
>>> just sane engineering.
> 
> Please just read the above again, and try to let it sink in.

I know what you mean, read on about this "unlucky situation" ..

> 
>>> On the actual content (and really, this is orthogonal to the above),
>>> I've repeatedly told you that I disagree with your approach to having
>>> several configuration files, having the distinction between "books" and
>>> other files, rewriting kernel-doc in python, having both rst and
>>> "vintage" kernel-doc comments, converting all the docbook files in one
>>> big lump. I won't repeat my rationale here, I've said it all before, but
>>> sadly I don't see any of that addressed.
> 
>> Take it as what it is: 
>> 
>>  a complete replacement of the XML toolchain.
>> 
>> IMHO, most of what you mentioned are assumptions, so my first 
>> question is:    
>> 
>>  have you pulled and tested?
> 
> I have looked at the patches and read the commit messages. If your work
> was reasonably based on docs-next, iteratively improving on what is
> there, we could have a sensible discussion on the relative merits of
> each commit and change. Now, it all depends on being a full rewrite. It
> depends on throwing out everything we've done so far. There isn't a
> single commit that's a change or an improvement to existing code.
> 
> I'm obviously biased because I've done the bulk of the Sphinx work in
> docs-next. Your pull request feels like a complicated way to tell me you
> think it's all crap. I'll try to let that slide.
> 
>> Since your solution is not a full replacement (no man-page builder) and 
>> does not produce structural markup .... 
>> 
>> IMHO pull my solution, if you have any remarks, let me know. E.g if
>> you think it is better to use ":no-header:" as default on DOC: 
>> sections, I implement it and test it against the complete docs.
> 
> You have plenty of good stuff in there. The annoying thing is that you
> present it in a take-it-all-or-leave-it-all kind of way.

Yes, this was my mistake I'am sorry about.

I started 4 or 5 month ago with the migration in my POC [1] I posted
it on the ML, to show those who had doubt in reST & sphinx that it is
the right decision to switch from DocBook to reST. But the only one how
gives feedback about this was Mauro. We discussed some points and he
explained me some of the developer's requirements, this was productive
and the flat-table is one of the results.

My mistake: after I finished the migration, I continued to
develop the sphinx extensions in the POC and not on the docs-next.
Then I switched to base on a 4.7rc tag... yes, complete chaotic 
Great mistake of mine not to base on the docs-next from the beginning.
... This is my first work in the kernel community and I was not familiar
with the organizational structures. I'am very sorry about and I will
improve myself on this.

In the further course you made huge steps forward and I thought
it is the best to let you work to get productive on that what you
have. While you needed to get productive, I needed more time,
it was "unlucky situation" ... 

side node: It is not really a good alternative, but the history is
present in the POC [1]. E.g. here is one patch from you I ported
to the python kernel-doc module: 

 https://github.com/return42/sphkerneldoc/commit/9ac8fc9023400d26a6a0b6e7f741e1bf788d2326

Yes, I read through all your patches, made tests with your perl
script and compared it with the python one ... I got huge
benefit from your patches -- the situation and my strategy
was unlucky, but your investigation is not lost! -- and
to fix kernel-doc comments is always good.

> For example, it would be trivial to add the flat table directive to the
> existing configuration file, but instead you opt to rewrite the entire
> file.

The config file "replacement" is because, that my configuration
with sub-project is different to the config file from the sphinx 
template. I also added more comments, dropped settings who are 
not relevant and I moved settings like project, author etc. to the
top ... but forgot to drop my latex settings .. not really perfect.

> You could base your kernel-doc directive extension on the existing
> one, but instead you rewrite it.

No this is not possible. After I realized, that I'am at the end with
the perl script and I needed a API to the kernel-doc parser I started
the kernel_doc.py rewrite ... so the kernel-doc directive of mine 
uses a kernel_doc.py API instead of pipes and a command line, thats
why the two implementation are so different.

> And then add it in the configuration
> file rewrite. And so on and so on.
> 
> I'll need to focus on other things now, and it's a good time to let
> others chime in. It would have been nice to see iterative improvements
> from you. Perhaps they could have made it to v4.8, the merge window
> being just a few weeks away.

Mauro will start to migrate, I think we need this time to get more
practice ... 

Regards

 -- Markus --


[1] https://github.com/return42/sphkerneldoc


> 
> BR,
> Jani.
> 
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center