Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1435362

Re: [PATCH] doc: flat-table directive

From Markus Heiser <markus.heiser@darmarit.de>
Newsgroups linux.kernel
Subject Re: [PATCH] doc: flat-table directive
Date 2016-07-01 16:20 +0200
Message-ID <rQ7st-7Fq-7@gated-at.bofh.it> (permalink)
References (2 earlier) <rPQhX-5fz-19@gated-at.bofh.it> <rQ2j8-4pm-23@gated-at.bofh.it> <rQ3oW-528-5@gated-at.bofh.it> <rQ5Al-6wz-1@gated-at.bofh.it> <rQ6wp-76i-3@gated-at.bofh.it>
Organization linux.* mail to news gateway

Show all headers | View raw

Am 01.07.2016 um 15:09 schrieb 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

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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarIT.de> - 2016-06-30 14:10 +0200
  [PATCH] doc-rst: flat-table directive - initial implementation Markus Heiser <markus.heiser@darmarIT.de> - 2016-06-30 14:10 +0200
  Re: [PATCH] doc: flat-table directive Jonathan Corbet <corbet@lwn.net> - 2016-06-30 21:10 +0200
    Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-06-30 21:40 +0200
    Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-06-30 22:00 +0200
      Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 10:50 +0200
        Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 12:00 +0200
          Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 12:50 +0200
            Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 13:20 +0200
              Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 14:00 +0200
                Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 14:10 +0200
                Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 14:30 +0200
                Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 15:20 +0200
                [docs-next PATCH] Documentation: add cleanmediadocs to the documentation targets Jani Nikula <jani.nikula@intel.com> - 2016-07-01 14:10 +0200
                [docs-next PATCH] Documentation/sphinx: skip build if user requested specific DOCBOOKS Jani Nikula <jani.nikula@intel.com> - 2016-07-01 14:30 +0200
                Re: [docs-next PATCH] Documentation/sphinx: skip build if user requested specific DOCBOOKS Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 14:40 +0200
                Re: [docs-next PATCH] Documentation/sphinx: skip build if user  requested specific DOCBOOKS Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 15:30 +0200
                Re: [docs-next PATCH] Documentation/sphinx: skip build if user requested specific DOCBOOKS Jani Nikula <jani.nikula@intel.com> - 2016-07-01 15:40 +0200
                Re: [docs-next PATCH] Documentation/sphinx: skip build if user  requested specific DOCBOOKS Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 17:10 +0200
            Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 15:00 +0200
            Re: [PATCH] doc: flat-table directive Jonathan Corbet <corbet@lwn.net> - 2016-07-01 15:30 +0200
              Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 16:50 +0200
                Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 19:30 +0200
                Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 20:20 +0200
                Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 20:50 +0200
          Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 14:20 +0200
            Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 15:20 +0200
              Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 16:20 +0200
                Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 17:10 +0200
                Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 17:10 +0200
                Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-07 01:00 +0200
            Re: [PATCH] doc: flat-table directive Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 15:20 +0200
      Re: [PATCH] doc: flat-table directive Jani Nikula <jani.nikula@intel.com> - 2016-07-01 14:30 +0200
    Re: [PATCH] doc: flat-table directive Markus Heiser <markus.heiser@darmarit.de> - 2016-07-01 08:40 +0200
  Captions numbering support Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-01 20:30 +0200

csiph-web