Re: [PATCH 00/10] Documentation/Sphinx

[Daniel Vetter]

On Fri, Jun 3, 2016 at 11:04 PM, Jonathan Corbet <corbet@xxxxxxx> wrote:
> On Mon, 30 May 2016 23:05:34 +0300
> Jani Nikula <jani.nikula@xxxxxxxxx> wrote:
>
>> To be clear, the "sphinx-for-docs-next" branch of [1], [2] is what I
>> propose to merge at this time. There's the Sphinx configuration, kernel
>> build integration, Sphinx kernel-doc extension, tons of kernel-doc
>> updates, etc.
>
> OK, I do believe that I am ready to do that.  Many, many thanks for doing
> this work!  Please drop me a note when you think that the branch is ready
> to go.

I've just fixed the last bug in the line number support. I guess next
week Jani will double-check that and then send out the patch bomb for
you. We have more ideas and work, but I think this is a very good
baseline to get going.

>> There is no DocBook tmpl conversion; all of that is left
>> to the authors (owners, maintainers) of the documents, but this enables
>> them to focus on that part.
>
> I would like to have some actual documents in there in the near future,
> so that interested folks have something to look at and start with.  Maybe
> I'll do that myself with some of the docbooks without active maintainers,
> or even, maybe, some of the .txt files :)

I definitely want to get gpu.tmpl converted for 4.8, but that's
probably better done in drm-misc instead of doc-next for coordination
with ongoing drm work. I'd also like to unify dma-buffer-sharing.txt
with the kerneldoc we have into one .rst. Jani has done all the
testing and development on a full conversion of all .tmpl files
(except media), so I guess we could convert all the others directly in
doc-next.

One bit to think of is how much we want to split things up. For gpu
and related documentation I think we'll go with Documentation/gpu/ and
then put an overview.rst, drm_kms.rst, drm_kms_helper.rst drm_uapi.rst
and so on in there. gpu.tmpl is way too big imo, the only reason we
had it all merged is to keep cross-referencing working. But with
sphinx that works across source files, and we can split things up
more. Many other docs seem fairly small in comparison, so maybe ok to
keep as-is.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch