Re: [PATCH] doc: flat-table directive

From	Jani Nikula <jani.nikula@intel.com>
Newsgroups	linux.kernel
Subject	Re: [PATCH] doc: flat-table directive
Date	2016-07-01 15:20 +0200
Message-ID	<rQ6wp-76i-3@gated-at.bofh.it> (permalink)
References	(1 earlier) <rPPvA-4YM-17@gated-at.bofh.it> <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>
Organization	Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo

Show all headers | View raw

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

> 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

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