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

[Jani Nikula <jani.nikula@intel.com>]

On Wed, 29 Jun 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 28.06.2016 um 21:05 schrieb Jani Nikula <jani.nikula@intel.com>:
>> 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.

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

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. You could base your kernel-doc directive extension on the existing
one, but instead you rewrite it. 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.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center