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. >> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
