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

[Jani Nikula]

On Tue, 28 Jun 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
> Hi Jonathan, hi Mauro,
>
> here is my DocBook to reST movement on top of Jon's docs-next branch. It includes:
>
> * kernel-doc parser & directive
> * flat-table directive
> * man page builder 'kernel-doc-man'
> * the kernel-doc-HOWTO
> * guides for starters (reST-nano-HOWTO.rst & template-book)
> * A index-page which bundles the lose Documentation/*.rst files.
> * sub sphinx-projects aka *books* under Documentation/*/conf.py
> * a full DocBook-XML to reST migration (*books* matching
>  Documentation/books_migrated/*/conf.py) described in [2]. The migration is
>  based on the DocBook-XML content at commit 17defc2 from Johnatan's docs-next
>  branch.
>
> I decided to comment out the pdf creation in the Makefile.reST, rst2pdf is to
> fragil see [2] (pdf is WIP).
>
> The output of html and man is included in the common %doc targets, to get
> more information about reST builds use:
>
>   make books-help 
>
> Any comments are welcome.

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.

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.

IMHO the most productive thing you could do right now is to send out
just the "flat table directive" patch. That's not controversial, and
would still have a chance to make it to v4.8.

BR,
Jani.

>
> -- Markus --
>
> [1] http://return42.github.io/sphkerneldoc/articles/dbtools.html
> [2] https://github.com/rst2pdf/rst2pdf/issues/556#issuecomment-228779542
>
>
> The following changes since commit 17defc282fe6e6ac93edbad8873ce89ef86b2490:
>
>  Documentation: add meta-documentation for Sphinx and kernel-doc (2016-06-24 06:55:28 -0600)
>
> are available in the git repository at:
>
>  https://github.com/return42/linux.git docs-next/linux-doc-reST
>
> for you to fetch changes up to 81bd813a599f8582570a735302ab660e20c7f442:
>
>  doc-rst: full DocBook-XML to reST migration (docs-next) (2016-06-28 17:15:38 +0200)
>
> ----------------------------------------------------------------
>
> Markus Heiser (15):
>      python: add scripts/site-packages
>      kernel-doc-HOWTO: add kernel-doc specification
>      doc-rst: add python package linuxdoc
>      doc-rst: kernel-doc parser - inital python implementation
>      doc-rst: kernel-doc directive - initial implementation
>      doc-rst: flat-table directive - initial implementation
>      doc-rst: kernel-doc-man sphinx builder - initial implementation
>      doc-rst: add basic sphinx-build infrastructure
>      doc-rst: add template book "Get started with reST"
>      doc-rst: removed Jani's kernel-documentation.rst and index.rst
>      doc-rst: infrastructure for *loose reST articles*
>      doc-rst: add build-html decription to book-help.
>      doc-rst: kernel-doc parser assert absolute pathname
>      doc-rst: infrastructure for migrated DocBook-XML
>      doc-rst: full DocBook-XML to reST migration (docs-next)
>

-- 
Jani Nikula, Intel Open Source Technology Center