Re: [PATCH] doc: flat-table directive

[Mauro Carvalho Chehab]

Em Fri, 1 Jul 2016 16:07:47 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:

> Am 01.07.2016 um 15:09 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:
> 
> > On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> 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  
> 
> Yes, "parsed literal" blocks is not the solution and I have none 
> yet ... and you are right, we need something "semi". I doubt whether we 
> will eventually find a solution for this, but I will
> think about it ... I don't know how, but it must be a solution that is
> transparent to the the pygment highlighter and not distort the
> node tree. I have to study the sphinx-writer and pygment first.

Yeah, a "semi" solution would be perfect. In the specific case of the
header files, a parsed literal should work. the code that generates
the *.h.xml files right now already does escaping where it needs to
make docbook happy. OK, the characters that need to be escaped will
be different, but shouldn't hard to do it, I guess. At the media
Makefile, it currently does escaping for <, > and &:

ESCAPE = \
	-e "s/&/\\&amp;/g" \
	-e "s/</\\&lt;/g" \
	-e "s/>/\\&gt;/g"

> 
> 
> >> 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.

I guess that will depend on how much care the subsystem maintainer has
with that. When building things on media, we have zero warnings when
building the Kernel with W=1 on x86. We also check both sparse and smatch 
regularly, trying zero the warnings there too (currently, there are just
a few of them, all false positives and not trivial to remove).

We also have zero warnings on media documentation using xmllint
pedantic mode.

> > 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.  
> 
> There is a nitpick_ignore config, but this will not help.
> As far as I can see, if you want similar on a per file basis,
> you need to implement a (HTML) builder which checks
> on which tree-level the *current* node is and if this node
> is in a doctree of one of your files in your *configured file-list*  
> then turns the warning into an error ... may we see more
> requirements coming into, which needs to implement a HTML-builder
> we can implement one. I have implemented a man-page builder
> for the kernel-doc comments, because it was inevitable
> but I think it is not a good idea to reimplement the
> HTML builder in this first usage of sphinx.
> 
> May this is the totally wrong way, may it is better
> to implement a *lint* builder from scratch (should not
> be hard).

That would work.

> 
> >> 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.  
> 
> IMHO it is not prefect but the most elaborate you will find in the net.
> 
> > Ideally, we should probably
> > keep the customization at a level where it's possible for people to
> > easily use different themes.  
> 
> Layout is done in the theme, we have no chance to influence 
> the layout out of / before the theme. 
> 
> > 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.  
> 
> Yes, KIS ... I send the theme patch and you will see that it contains only 
> a view lines pointing exactly what we need. And with the builtin-extensions,
> I think it will be good to activate common used extensions ...
> 
> * todolist: http://www.sphinx-doc.org/en/stable/ext/todo.html and

I don't see much usage for todos at the media documentation, as we
basically reject patches that don't come with a proper documentation.

Ok, there are a few things that need extra care at the DVB side of the
spec. So, maybe a todo might be useful there for a while.

> * intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

Yeah, this sounds interesting. We would have one usage for it: to point
to the ALSA spec for the audio part of a media device.

I guess this could also be useful for the media controller, as other
subsystems are starting to use it.

Regards,
Mauro