Re: [PATCH] doc: flat-table directive

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

On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> In Sphinx, the code-block directive is a literal block, no refs or markup
> will be interpreted. This is different to what you know from DocBook.
> I will look for a solution, that matches your requirement.

Parsed literal block solves the problem, but brings other problems like
requiring escaping for a lot of stuff. And you lose syntax
highlighting. It would be great to have a middle ground, like a
"semi-parsed code block" where the references are parsed but nothing
else.

http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

> OK, checking dead internal links might be one requirement more. Normally 
> sphinx reports internal refs which are broken with a WARNING, but I have to
> analyze what xmllint checks and how we could realize something similar
> in sphinx / or if it is enough what sphinx reports.

When we turn function() and &struct structure references to Sphinx
references, we pretty much rely on *not* being strict about all the
targets existing. At least for now. In an ideal world we'd aim for -n
and -W sphinx-build options, but we're far from that, and I don't know
if it's really possible ever.

Is it possible to set -n and/or -W on a per-rst file basis, either in
the top config file or from within the rst file itself? Then we could
gradually improve this, and subsystems that really care about this could
be in the forefront.

> But before I will send out some small patches which are needed 
> first (IMHO). E.g. customizing the RTD theme for rendering large 
> tables in HTML well and activation of useful extensions like todolist.
> I have this in my "chaotic bulk" patch :-) ... I will separate it out
> an send it to Jon one by one.

Btw I don't think we are really attached to the RTD theme. It's just
something I picked that was prettier than the default theme, and was
widely available and packaged in distros. Ideally, we should probably
keep the customization at a level where it's possible for people to
easily use different themes. That said, rendering big tables in the RTD
theme is definitely an issue.

I'd also aim to be fairly conservative at first in terms of the rst
features and Sphinx extensions we use. Keep it simple. It's really easy
to go overboard in the beginning. See how things pan out and gradually
extend from there.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center