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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
