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

Groups > linux.kernel > #1434485 > unrolled thread

[PATCH] doc: flat-table directive

Back to article view | Back to linux.kernel

Contents

  [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

Page 2 of 2 — ← Prev page 1 [2]

#1435328

On Fri, 01 Jul 2016 13:44:17 +0300
Jani Nikula <jani.nikula@intel.com> wrote:

> This is also one of the reasons why I so much want to keep everything
> behind one configuration file, and build everything in the Sphinx
> toolchain. To keep it all more uniform, to not duplicate stuff, and not
> deviate to some silos like we've done in the past. I think when we have
> things working, we can add dedicated config files for the select few
> things that have additional special needs. Media is probably one of
> them. But that said, I think we should be able to keep including that to
> the main documentation build too.

So this is mostly how I see things too.  But it might still be worth
thinking about whether media, in particular, is special and should be
buildable as a standalone document.  I can see there may be settings
where only that is wanted.

Some sort of "only build xxx.rst and see what explodes" makefile option
also seems like a useful thing to have, just as a time saver for
developers and maintainers.

jon

[toc] | [prev] | [next] | [standalone]

#1435393

Am 01.07.2016 um 14:58 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Fri, 01 Jul 2016 13:44:17 +0300
> Jani Nikula <jani.nikula@intel.com> wrote:
> 
>> This is also one of the reasons why I so much want to keep everything
>> behind one configuration file, and build everything in the Sphinx
>> toolchain. To keep it all more uniform, to not duplicate stuff, and not
>> deviate to some silos like we've done in the past. I think when we have
>> things working, we can add dedicated config files for the select few
>> things that have additional special needs. Media is probably one of
>> them. But that said, I think we should be able to keep including that to
>> the main documentation build too.
> 
> So this is mostly how I see things too.  But it might still be worth
> thinking about whether media, in particular, is special and should be
> buildable as a standalone document.  I can see there may be settings
> where only that is wanted.
> 

I dare hardly say it, but I come back to the sphinx-sub-project
solution ... don't hurt me ... listen, it is conceptual a bit 
different to what I have done first, but hopefully it is a solution
we can all live with:

* media is "special", so let's build it separate.
 
We have this Documentation/index.rst file, where we can place
all "books" in, except those which are specifically.

.. toctree::
   :maxdepth: 2

   kernel-documentation
   gpu
   ...

Folders matching Documentation/*/conf.py are build separate,
media is the one. This is exactly what my sphinx-sub-project
solution does, building books from folders with a conf.py in.
This conf.py inherits all settings from the top config in
Documentation/conf.py and overwrites only those configurations
which are different.

... could this be a solution?

... I'm a bit afraid to press the send button ... ;-)

> Some sort of "only build xxx.rst and see what explodes" makefile option
> also seems like a useful thing to have, just as a time saver for
> developers and maintainers.
> 
> jon

IMHO it is a conceptual problem:

If we assemble "books" into one project, the context of each
node in the doctree is the union. E.g. cross references from
one "book" to another will only work if the context is the union. 

No matter how we do it, but if we are building parts, the context
is reduced to this part and this will always be different to build
the union, so it could never be a entire *lint*.

-- Markus --

[toc] | [prev] | [next] | [standalone]

#1435510

On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 01.07.2016 um 14:58 schrieb Jonathan Corbet <corbet@lwn.net>:
>
>> On Fri, 01 Jul 2016 13:44:17 +0300
>> Jani Nikula <jani.nikula@intel.com> wrote:
>> 
>>> This is also one of the reasons why I so much want to keep everything
>>> behind one configuration file, and build everything in the Sphinx
>>> toolchain. To keep it all more uniform, to not duplicate stuff, and not
>>> deviate to some silos like we've done in the past. I think when we have
>>> things working, we can add dedicated config files for the select few
>>> things that have additional special needs. Media is probably one of
>>> them. But that said, I think we should be able to keep including that to
>>> the main documentation build too.
>> 
>> So this is mostly how I see things too.  But it might still be worth
>> thinking about whether media, in particular, is special and should be
>> buildable as a standalone document.  I can see there may be settings
>> where only that is wanted.
>> 
>
> I dare hardly say it, but I come back to the sphinx-sub-project
> solution ... don't hurt me ... listen, it is conceptual a bit 
> different to what I have done first, but hopefully it is a solution
> we can all live with:
>
> * media is "special", so let's build it separate.
>  
> We have this Documentation/index.rst file, where we can place
> all "books" in, except those which are specifically.
>
> .. toctree::
>    :maxdepth: 2
>
>    kernel-documentation
>    gpu
>    ...
>
> Folders matching Documentation/*/conf.py are build separate,
> media is the one. This is exactly what my sphinx-sub-project
> solution does, building books from folders with a conf.py in.
> This conf.py inherits all settings from the top config in
> Documentation/conf.py and overwrites only those configurations
> which are different.
>
> ... could this be a solution?
>
> ... I'm a bit afraid to press the send button ... ;-)

Hey, the discussions can sometimes be heated, but you should never have
to worry about expressing your opinions.

You know I'm opposed to adding several configs and building things
separately. Some of the reasons are to keep things (especially the
Makefiles and configs) simple and easy for the wider audience to
understand, and to agressively promote finding generic solutions that
work for everyone. Sure, maybe this won't completely work in the end,
but it sure as hell won't work if we don't even try.

The current media DocBook docs are a prime example. There are really
great features there, but IMHO done in a really complicated way and
specifically for media documentation (sorry Mauro). I think we'd be in a
better position now if all of that had been done in a more generic way
for all the DocBook docs. So I just want to avoid that for Sphinx, now
that we have a chance for a fresh start.

>> Some sort of "only build xxx.rst and see what explodes" makefile option
>> also seems like a useful thing to have, just as a time saver for
>> developers and maintainers.
>> 
>> jon
>
> IMHO it is a conceptual problem:
>
> If we assemble "books" into one project, the context of each
> node in the doctree is the union. E.g. cross references from
> one "book" to another will only work if the context is the union. 
>
> No matter how we do it, but if we are building parts, the context
> is reduced to this part and this will always be different to build
> the union, so it could never be a entire *lint*.

This is another reason why I like the "everything together" approach. I
like the cross-references from kernel-doc comments to work beyond one
subsystem. I like to have the function() and &struct style references
from GPU documentation to the kernel API and device documents just
work. AFAICT intersphinx doesn't solve this because kernel-doc has no
way of knowing where the target exists. For GPU documentation, putting
it into a silo would be giving up on the goals we had.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1435536

Em Fri, 01 Jul 2016 20:24:48 +0300
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> > Am 01.07.2016 um 14:58 schrieb Jonathan Corbet <corbet@lwn.net>:
> >  
> >> On Fri, 01 Jul 2016 13:44:17 +0300
> >> Jani Nikula <jani.nikula@intel.com> wrote:
> >>   
> >>> This is also one of the reasons why I so much want to keep everything
> >>> behind one configuration file, and build everything in the Sphinx
> >>> toolchain. To keep it all more uniform, to not duplicate stuff, and not
> >>> deviate to some silos like we've done in the past. I think when we have
> >>> things working, we can add dedicated config files for the select few
> >>> things that have additional special needs. Media is probably one of
> >>> them. But that said, I think we should be able to keep including that to
> >>> the main documentation build too.  
> >> 
> >> So this is mostly how I see things too.  But it might still be worth
> >> thinking about whether media, in particular, is special and should be
> >> buildable as a standalone document.  I can see there may be settings
> >> where only that is wanted.
> >>   
> >
> > I dare hardly say it, but I come back to the sphinx-sub-project
> > solution ... don't hurt me ... listen, it is conceptual a bit 
> > different to what I have done first, but hopefully it is a solution
> > we can all live with:
> >
> > * media is "special", so let's build it separate.
> >  
> > We have this Documentation/index.rst file, where we can place
> > all "books" in, except those which are specifically.
> >
> > .. toctree::
> >    :maxdepth: 2
> >
> >    kernel-documentation
> >    gpu
> >    ...
> >
> > Folders matching Documentation/*/conf.py are build separate,
> > media is the one. This is exactly what my sphinx-sub-project
> > solution does, building books from folders with a conf.py in.
> > This conf.py inherits all settings from the top config in
> > Documentation/conf.py and overwrites only those configurations
> > which are different.
> >
> > ... could this be a solution?
> >
> > ... I'm a bit afraid to press the send button ... ;-)  
> 
> Hey, the discussions can sometimes be heated, but you should never have
> to worry about expressing your opinions.
> 
> You know I'm opposed to adding several configs and building things
> separately. Some of the reasons are to keep things (especially the
> Makefiles and configs) simple and easy for the wider audience to
> understand, and to agressively promote finding generic solutions that
> work for everyone. Sure, maybe this won't completely work in the end,
> but it sure as hell won't work if we don't even try.
> 
> The current media DocBook docs are a prime example. There are really
> great features there, but IMHO done in a really complicated way and
> specifically for media documentation (sorry Mauro).

My view is just the reverse of yours: the non-media documentation is
too simple, and has lots of gaps ;)

Anyway, the media documentation actually started out of the tree,
by the time Alan Cox were the V4L2 maintainer, as two separate documents. 
The first one written 1999 (v4l2) and the second one in 2001 (dvb).
They were merged upstream by 2006 or 2007, after several conversions
(the DVB doc were in LaTex, and the V4L2 one, were on a very old 
DocBook version).

We're doing a real hard work to keep it updated over the last 10
years, and we just don't want to throw it away and do a fresh
start. Whatever we do, we should not lost documentation nor lost
the scripts that have been working so well to enforce the docs
to keep updated as we touch on the code.

> I think we'd be in a
> better position now if all of that had been done in a more generic way
> for all the DocBook docs. So I just want to avoid that for Sphinx, now
> that we have a chance for a fresh start.
> 
> >> Some sort of "only build xxx.rst and see what explodes" makefile option
> >> also seems like a useful thing to have, just as a time saver for
> >> developers and maintainers.
> >> 
> >> jon  
> >
> > IMHO it is a conceptual problem:
> >
> > If we assemble "books" into one project, the context of each
> > node in the doctree is the union. E.g. cross references from
> > one "book" to another will only work if the context is the union. 
> >
> > No matter how we do it, but if we are building parts, the context
> > is reduced to this part and this will always be different to build
> > the union, so it could never be a entire *lint*.  
> 
> This is another reason why I like the "everything together" approach. I
> like the cross-references from kernel-doc comments to work beyond one
> subsystem. I like to have the function() and &struct style references
> from GPU documentation to the kernel API and device documents just
> work. AFAICT intersphinx doesn't solve this because kernel-doc has no
> way of knowing where the target exists. For GPU documentation, putting
> it into a silo would be giving up on the goals we had.

Having the capability of integrating with other documents is a nice
thing. However, the media uAPI book will have *very few* outside
references (right now, I can think on just one reference, at the
introduction that mentions the ALSA project - even so, maybe the
best would be to point to the ALSA project website, but, if we
decide to point to the internal ALSA docs, we could use intersphinx). 
The reason for that is simple: it describes the API from the Kernel
to userspace, and not the Kernel's internal API.

The Media Kernel's internal API is described at the media section of
the device-drivers.xml. There, references to the other Kernel-doc
documented APIs is very welcomed.

Regards,
Mauro

[toc] | [prev] | [next] | [standalone]

#1435551

On Fri, 01 Jul 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> Em Fri, 01 Jul 2016 20:24:48 +0300
> Jani Nikula <jani.nikula@intel.com> escreveu:
>> The current media DocBook docs are a prime example. There are really
>> great features there, but IMHO done in a really complicated way and
>> specifically for media documentation (sorry Mauro).
>
> My view is just the reverse of yours: the non-media documentation is
> too simple, and has lots of gaps ;)

Heh, can't argue with that.

> We're doing a real hard work to keep it updated over the last 10
> years, and we just don't want to throw it away and do a fresh
> start. Whatever we do, we should not lost documentation nor lost
> the scripts that have been working so well to enforce the docs
> to keep updated as we touch on the code.

I hear you. I just want to make it work nicely for everybody. Including
media docs.


BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1435285

Am 01.07.2016 um 11:38 schrieb Mauro Carvalho Chehab <mchehab@osg.samsung.com>:


> Btw, yesterday, I tried to add references to a C code, at video.rst,
> just like we did with DocBook:
> 
> .. code-block:: c
>   :caption: Example 2: Switching to the first video input
> 
>   int index;
> 
>   index = 0;
> 
>   if (-1 == ioctl(fd, :ref:`VIDIOC_S_INPUT <vidioc-s-input>`, &index)) {
>       perror("VIDIOC_S_INPUT");
>       exit(EXIT_FAILURE);
>   }
> 
> But Sphinx didn't allow doing it. I was unable to find any syntax
> on it that would make Sphinx use a monospaced font but still parse
> the references at the code. While for those small examples this would
> be ok, This is something that we do want for the header files that
> we put at V4L and DVB annexes. For DocBook, we do a lot of things like
> this at the DocBook/media/Makefile:
> 	sed -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" videodev2.h

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.

> The actual code is a way more complex, but basically the idea is that
> it escapes anything that DocBook might interpret as a command, and adds
> <link> tags for every enum, typedef, ioctl, struct, syscall and define
> it founds at the header files. the xmllint will produce errors when
> links are not solved, and we'll be able to detect that the API is not
> fully documented.

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. 

> We need to do a similar process with Sphinx. A side effect is that, if
> someone looks at the header files in the anexes, it can click on any
> symbol at the API and see the full documentation.

Yes, altogether, it seems to be a nice feature, I have to think about. But
I will point it in a separate thread.

> --
> 
> Btw, in the case of the above example, I had to manually number it as
> "Example 2", because I was unable to find a way with Sphinx to auto
> numerate code-block captions. This is also something we want to fix,
> as it is very hard to manually number things on a 600+ page document.
> 

This needs a sphinx extension, I have seen similar solutions for 
numbering figures on the net ... I will try to find a small solution.

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.

-- Markus --

> Regards,
> Mauro

[toc] | [prev] | [next] | [standalone]

#1435315

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

[toc] | [prev] | [next] | [standalone]

#1435362

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

[toc] | [prev] | [next] | [standalone]

#1435400

Em Fri, 1 Jul 2016 16:07:47 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

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

Yeah, a "semi" solution would be perfect. In the specific case of the
header files, a parsed literal should work. the code that generates
the *.h.xml files right now already does escaping where it needs to
make docbook happy. OK, the characters that need to be escaped will
be different, but shouldn't hard to do it, I guess. At the media
Makefile, it currently does escaping for <, > and &:

ESCAPE = \
	-e "s/&/\\&amp;/g" \
	-e "s/</\\&lt;/g" \
	-e "s/>/\\&gt;/g"

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

I guess that will depend on how much care the subsystem maintainer has
with that. When building things on media, we have zero warnings when
building the Kernel with W=1 on x86. We also check both sparse and smatch 
regularly, trying zero the warnings there too (currently, there are just
a few of them, all false positives and not trivial to remove).

We also have zero warnings on media documentation using xmllint
pedantic mode.

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

That would work.

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

I don't see much usage for todos at the media documentation, as we
basically reject patches that don't come with a proper documentation.

Ok, there are a few things that need extra care at the DVB side of the
spec. So, maybe a todo might be useful there for a while.

> * intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

Yeah, this sounds interesting. We would have one usage for it: to point
to the ALSA spec for the audio part of a media device.

I guess this could also be useful for the media controller, as other
subsystems are starting to use it.

Regards,
Mauro

[toc] | [prev] | [next] | [standalone]

#1435408

Em Fri, 1 Jul 2016 16:07:47 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

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

Yeah, a "semi" solution would be perfect. In the specific case of the
header files, a parsed literal should work. the code that generates
the *.h.xml files right now already does escaping where it needs to
make docbook happy. OK, the characters that need to be escaped will
be different, but shouldn't hard to do it, I guess. At the media
Makefile, it currently does escaping for <, > and &:

ESCAPE = \
	-e "s/&/\\&amp;/g" \
	-e "s/</\\&lt;/g" \
	-e "s/>/\\&gt;/g"

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

I guess that will depend on how much care the subsystem maintainer has
with that. When building things on media, we have zero warnings when
building the Kernel with W=1 on x86. We also check both sparse and smatch 
regularly, trying zero the warnings there too (currently, there are just
a few of them, all false positives and not trivial to remove).

We also have zero warnings on media documentation using xmllint
pedantic mode.

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

That would work.

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

I don't see much usage for TODOs at the media documentation, as we
basically reject patches that don't come with a proper documentation.

Ok, there are a few things that need extra care at the DVB side of the
spec. So, maybe a todo might be useful there for a while.

> * intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

Yeah, this sounds interesting. We would have one usage for it: to point
to the ALSA spec for the audio part of a media device.

I guess this could also be useful for the media controller, as other
subsystems are starting to use it.

Regards,
Mauro

[toc] | [prev] | [next] | [standalone]

#1438001

Em Fri, 1 Jul 2016 16:07:47 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> 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  

OK, using parsed literal indeed seems to be a solution. The script below
should be doing what's needed to auto-generate the *.h.rst files.
It should be replicating the logic that is done at the media Makefile,
on a cleaner way. It also allows ignoring some symbols. We do that when
we deprecate APIs: they're kept at the header files, but their
descriptions are removed/replaced at the media book.

This is not yet the final version. I need to do some adjustments, as
only the ioctl refs match the ones on media, but it shouldn't be hard to
fix.


Thanks,
Mauro



#!/usr/bin/perl
use strict;

# change to 1 to generate some debug prints
my $debug = 1;

if (scalar @ARGV < 2 || scalar @ARGV > 3) {
	die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
}

my ($file_in, $file_out, $file_exceptions) = @ARGV;

my $data;
my @ioctls;
my @defines;
my @typedefs;
my @enums;
my @enum_symbols;
my @structs;

#
# read the file and get identifiers
#

my $is_enum = 0;
open IN, $file_in or die "Can't open $file_in";
while (<IN>) {
	$data .= $_;

	if ($is_enum && m/^\s*([^\s\}]+)\s*[\,=]?/) {
		my $s = $1;
		push @enum_symbols, $1;

		$is_enum = 0 if ($is_enum && m/\}/);

		next;
	}
	$is_enum = 0 if ($is_enum && m/\}/);

	if (m/^\s*#\s*define\s+([A-Z]\S+)\s+_IO/) {
		push @ioctls, $1;
		next;
	}

	if (m/^\s*#\s*define\s+([A-Z]\S+)\s+/) {
		push @defines, $1;
		next
	}

	if (m/^\s*typedef\s+.*\s+(\w\S+);/) {
		push @typedefs, $1;
		next;
	}
	if (m/^\s*enum\s+(\S+)\s+\{/ || m/^\s*enum\s+(\S+)$/) {
		my $v = $1;
		push @enums, $v unless grep{$_ eq $v} @enums;
		$is_enum = $1;
		next;
	}
	if (m/^\s*struct\s+(\S+)\s+\{/ || m/^\s*struct\s+(\S+)$/) {
		my $v = $1;
		push @structs, $v unless grep{$_ eq $v} @structs;
		next;
	}
}
close IN;

#
# Handle multi-line typedefs
#

my @matches = $data =~ m/typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*(\S+)\s*\;/g;
foreach my $m (@matches) {
	push @typedefs, $m unless grep{$_ eq $m} @typedefs;
	next;
}

#
# Handle exceptions, if any
#

if ($file_exceptions) {
	open IN, $file_exceptions or die "Can't read $file_exceptions";
	while (<IN>) {
		next if (m/^\s*$/ || m/^\s*#/);
		if (m/^ignore\s+ioctl\s+(\S+)/) {
			@ioctls = grep { $_ != $1 } @ioctls;
			next;
		}
		if (m/^ignore\s+define\s+(\S+)/) {
			@defines = grep { $_ != $1 } @defines;
			next;
		}
		if (m/^ignore\s+typedef\s+(\S+)/) {
			@typedefs = grep { $_ != $1 } @typedefs;
			next;
		}
		if (m/^ignore\s+enum\s+(\S+)/) {
			@enums = grep { $_ != $1 } @enums;
			next;
		}
		if (m/^ignore\s+struct\s+(\S+)/) {
			@structs = grep { $_ != $1 } @structs;
			next;
		}
		die "Can't parse $file_exceptions";
	}
}

print "ioctls: @ioctls\n" if ($debug && @ioctls);
print "defines: @defines\n" if ($debug && @defines);
print "typedefs: @typedefs\n" if ($debug && @typedefs);
print "enums: @enums\n" if ($debug && @enums);
print "structs: @structs\n" if ($debug && @structs);

#
# Add escape codes for special characters
#
$data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;

#
# Align block
#
$data = "    " . $data;
$data =~ s/\n/\n    /g;
$data =~ s/\n\s+$/\n/g;

#
# Add references
#

foreach my $r (@ioctls, @defines, @enum_symbols) {
	my $n = $r;
	$n =~ tr/A-Z/a-z/;
	my $s = ":ref:`$r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/([\s])($r)([\s])/$1$s$3/g;
}

foreach my $r (@enums) {
	my $n = $r;
	$n =~ tr/A-Z_/a-z-/;
	my $s = ":ref:`enum $r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/enum\s+($r)([\s])/$s$2/g;
}

foreach my $r (@structs) {
	my $n = $r;
	$n =~ tr/A-Z_/a-z-/;
	my $s = ":ref:`struct $r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/struct\s+($r)([\s])/$s$2/g;
}

## FIXME

foreach my $r (@typedefs) {
	my $n = $r;
	$n =~ tr/A-Z_/a-z-/;
	my $s = ":ref:`$r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/(typedef\s+^\n+\s+)($r)(\s*;)/$1$s$3/g;
	$data =~ s/(typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*)($r)(\s*;)/$1$s$3/g;
}

#
# Generate output file
#

my $title = $file_in;
$title =~ s,.*/,,;

open OUT, "> $file_out" or die "Can't open $file_out";
print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";
print OUT "$title\n";
print OUT "=" x length($title);
print OUT "\n\n.. parsed-literal::\n\n";
print OUT $data;
close OUT;

[toc] | [prev] | [next] | [standalone]

#1435322

Em Fri, 1 Jul 2016 14:18:34 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 01.07.2016 um 11:38 schrieb Mauro Carvalho Chehab <mchehab@osg.samsung.com>:
> 
> 
> > Btw, yesterday, I tried to add references to a C code, at video.rst,
> > just like we did with DocBook:
> > 
> > .. code-block:: c
> >   :caption: Example 2: Switching to the first video input
> > 
> >   int index;
> > 
> >   index = 0;
> > 
> >   if (-1 == ioctl(fd, :ref:`VIDIOC_S_INPUT <vidioc-s-input>`, &index)) {
> >       perror("VIDIOC_S_INPUT");
> >       exit(EXIT_FAILURE);
> >   }
> > 
> > But Sphinx didn't allow doing it. I was unable to find any syntax
> > on it that would make Sphinx use a monospaced font but still parse
> > the references at the code. While for those small examples this would
> > be ok, This is something that we do want for the header files that
> > we put at V4L and DVB annexes. For DocBook, we do a lot of things like
> > this at the DocBook/media/Makefile:
> > 	sed -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" videodev2.h  
> 
> 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.

Ok, thanks!

> > The actual code is a way more complex, but basically the idea is that
> > it escapes anything that DocBook might interpret as a command, and adds
> > <link> tags for every enum, typedef, ioctl, struct, syscall and define
> > it founds at the header files. the xmllint will produce errors when
> > links are not solved, and we'll be able to detect that the API is not
> > fully documented.  
> 
> 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. 

An option at Sphinx to handle warnings as errors would be useful. Yet,
it is not hard to modify my build scripts to handle WARNING as errors.

> 
> > We need to do a similar process with Sphinx. A side effect is that, if
> > someone looks at the header files in the anexes, it can click on any
> > symbol at the API and see the full documentation.  
> 
> Yes, altogether, it seems to be a nice feature, I have to think about. But
> I will point it in a separate thread.

Ok, thanks!

> > Btw, in the case of the above example, I had to manually number it as
> > "Example 2", because I was unable to find a way with Sphinx to auto
> > numerate code-block captions. This is also something we want to fix,
> > as it is very hard to manually number things on a 600+ page document.
> >   
> 
> This needs a sphinx extension, I have seen similar solutions for 
> numbering figures on the net ... I will try to find a small solution.

Yeah, we'll need this for figures and tables too.

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

Ah, yes, I noticed that the .. todolist was causing warnings...
I ended by adding a patch removing it internally, as there weren't
anything at the todo block :)

> I will separate it out an send it to Jon one by one.

OK!

Thanks!
Mauro

[toc] | [prev] | [next] | [standalone]

#1435290

On Thu, 30 Jun 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> Em Thu, 30 Jun 2016 13:05:11 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> Anyway, I don't want to delay this work, so I have gone ahead and applied
>> it; 
>
> Got already one issue... Maybe on Jeni's changes to the makefiles...
>
> I want to be able to compile just the book I'm working. Using the usual
> syntax to build just one book worked: the build from the *.rst files
> succeeded. Yet, it tried to compile it also as DocBook, causing an
> error at the end.
>
> See the logs below:
>
> $ make DOCBOOKS=linux_tv htmldocs
>   SPHINX  htmldocs
> Running Sphinx v1.3.1
> loading pickled environment... done
> building [mo]: targets for 0 po files that are out of date
> building [html]: targets for 1 source files that are out of date
> updating environment: 0 added, 1 changed, 0 removed
> reading sources... [100%] linux_tv/media/dvb/dvbapi                             
> looking for now-outdated files... none found
> pickling environment... done
> checking consistency... done
> preparing documents... done
> writing output... [100%] linux_tv/media/dvb/dvbapi                              
> generating indices... genindex
> writing additional pages... search
> copying images... [100%] linux_tv/media_api_files/typical_media_device.svg      
> copying static files... done
> copying extra files... done
> dumping search index in English (code: en) ... done
> dumping object inventory... done
> build succeeded.
> make[1]: *** No rule to make target 'Documentation/DocBook/linux_tv', needed by 'htmldocs'.  Pare.
> Makefile:1420: recipe for target 'htmldocs' failed
> make: *** [htmldocs] Error 2

This is just because there isn't a DocBook called linux_tv. DOCBOOKS
means nothing to Sphinx, it's only relevant for DocBook build. Top level
'make help' lists the valid values for DOCBOOKS.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1435046

Am 30.06.2016 um 21:05 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Thu, 30 Jun 2016 14:00:21 +0200
> Markus Heiser <markus.heiser@darmarIT.de> wrote:
> 
>> this is my flat-table patch on top of your docs-next branch / we discussed on
>> the ML
> 
> Hmm...  we don't have an official kernel coding style for Python, but if
> we did, I'd sure like it to be a lot more like the usual Python
> conventions.

Please help me, what in the patch is not usual Python? 

There is a "Style Guide for Python Code" PEP 8 [1] from which
I (hopefully) differ only in marginal details. I use the 
pylint [3] which checks PEP8 style, may I switched of to much?
E.g. the "one-liner classes" of mine is not PEP8 style, is this what
you mean? Or is it about the (comma) operators in front of
a new line [2]? Could you give me more detail hints / thanks.

[1] https://www.python.org/dev/peps/pep-0008/
[2] https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator
[3] https://www.pylint.org/

> The added documentation describes the "widths" parameter, but does not
> tell the reader which units are used.

It has no units, it's relativ. Sorry, I implied that it is a common practice
on table layouts [4]:

  """A comma- or space-separated list of relative column widths. 
     The default is equal-width columns (100%/#columns)."""

[4] http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table 

> There were also a lot of typos and misspellings in the documentation
> addition.

Sorry, I did it in a hurry because Mauro needs it promptly. I will improve 
myself in the future.

> Anyway, I don't want to delay this work, so I have gone ahead and applied
> it; I fixed the spelling errors on the way.

Thanks a lot!

>  When you get a chance, can I
> get a doc tweak for :widths:?

Yes, I will send you a patch later.

-- Markus --

> Thanks for separating this work out,
> 
> jon

[toc] | [prev] | [next] | [standalone]

#1435539 — Captions numbering support

Markus/Jani,

I'm starting this as a new thread, as it is not directly related to the
other subjects.

I'm fixing right now the captions that got missed during the docbook
conversion. See for example:

https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=69f9771c659958ecc7c8ba26e85c2f61f821b022
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=56bd374200a15e8888d94fd8410eea916bffea87

As I mentioned before, I'm needing to re-numerate by hand the examples.

I'm wandering if are there any way with Sphinx to use the section
numbering. If so, then we could number the examples as:

1.4 section title
...
1.4.1 Example foo
1.4.2 Example bar
...
1.6 section title 2
...
1.6.1 Exampel foobar

With would make a way easier to keep handling it, while we don't
have ":numbered:" support for the code-block.

Do you know if are there anything like that in Sphinx?

Regards,
Mauro

[toc] | [prev] | [standalone]

Page 2 of 2 — ← Prev page 1 [2]

Back to top | Article view | linux.kernel

csiph-web