Message-Id: <AB1BFD5C-6FAB-494C-874E-9CC35911C252@darmarit.de>
Date:	Fri, 1 Jul 2016 16:07:47 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jani Nikula <jani.nikula@...el.com>
Cc:	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org, hverkuil@...all.nl,
	daniel.vetter@...ll.ch, airlied@...il.com,
	grant.likely@...retlab.ca, rdunlap@...radead.org, keithp@...thp.com
Subject: Re: [PATCH] doc: flat-table directive


Am 01.07.2016 um 15:09 schrieb Jani Nikula <jani.nikula@...el.com>:

> On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@...marit.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

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.


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

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

>> 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
* intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

should be enabled. 

-- Markus --



> 
> BR,
> Jani.
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

Powered by blists - more mailing lists