Re: Kernel docs: muddying the waters a bit

[Jani Nikula]

On Wed, 09 Mar 2016, Dan Allen <dan@xxxxxxxxxxxxx> wrote:
> On Tue, Mar 8, 2016 at 6:58 AM, Jani Nikula <jani.nikula@xxxxxxxxx> wrote:
>
>> I need to look into this again. Is there a specific option or directive
>> to produce split output for includes? When I tried this, the result was
>> just one big output file. (And indeed we'd need both. Some includes we
>> want embedded, some includes should produce separate outputs.)
>>
>
> Nope. What I'm saying is that you run Asciidoctor on each sub-master
> include file (an include that manages a part or chapter). That gives you
> your individual part/chapter files. Then you need to make an index page,
> probably by using the Asciidoctor API to itemize all the chapters as a list
> or something.

Bummer.

Getting the inter-document cross references right may become
tricky. We'll be generating plenty of snippets of lightweight markup
from source code documentation comments. At the time of processing, we
won't know where e.g. a specific function to be cross referenced is
documented, if at all. We can't require the documentation comment
writers to figure that out either; it's too burdensome, too ugly in the
code, and they'll bitrot quickly.

Cross referencing in the asciidoc proofs of concept have worked because
they've all done the processing as a single single unit, with
includes. These hacks have also ignored any broken links, and there have
been

> Yes, it does require some thinking about cross references. There is a lot
> more we can do out of the box, but all those references can be fixed with a
> little bit of post-processing in the meantime.

It seems to me Sphinx provides much better support regarding cross
references, out of the box, within documents and to external documents
(intersphinx), with target roles and domains, including validation and
not creating broken links in the output.

Looking at the current hacks we have for post-processing references, I'm
really not thrilled about the prospect of keeping or redoing that.

See how this works in Jon's Sphinx test [1]. At the time of generating
the markup from source comments, there is no idea if and where
gem_init_hw() and intel_guc_ucode_init() are documented. Indeed,
documentation for the former does not exist, but there's no broken link.

BR,
Jani.


[1] http://static.lwn.net/kerneldoc/gpu.html#c.intel_guc_ucode_load


-- 
Jani Nikula, Intel Open Source Technology Center