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