[PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Mauro Carvalho Chehab]

Sphinx 1.4.5 complains about some literal blocks at
kernel-documentation.rst:

	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.

Fix it by telling Sphinx to consider them as "none" type.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/kernel-documentation.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 391decc66a18..1dd97478743e 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -370,11 +370,15 @@ To cross-reference the functions and types defined in the kernel-doc comments
 from reStructuredText documents, please use the `Sphinx C Domain`_
 references. For example::
 
+.. code-block:: none
+
   See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
 
 While the type reference works with just the type name, without the
 struct/union/enum/typedef part in front, you may want to use::
 
+.. code-block:: none
+
   See :c:type:`struct foo <foo>`.
   See :c:type:`union bar <bar>`.
   See :c:type:`enum baz <baz>`.
@@ -573,6 +577,8 @@ converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
 enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
 which uses ``pandoc`` under the hood. For example::
 
+.. code-block:: none
+
   $ cd Documentation/sphinx
   $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
 
-- 
2.7.4

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Markus Heiser]

Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Sphinx 1.4.5 complains about some literal blocks at
> kernel-documentation.rst:
> 
> 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> 
> Fix it by telling Sphinx to consider them as "none" type.

Hi Mauro,

IMHO we should better fix this by unsetting the lexers default language 
in the conf.py  [1] ... currently:

highlight_language = 'C'  # set this to 'none'
	
As far as I know the default highlight_language is also the default
for literal blocks starting with "::"

<SNIP>---
references. For example::

 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
<SNAP>---

[1] http://www.sphinx-doc.org/en/stable/config.html#confval-highlight_language

-- Markus --

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> Documentation/kernel-documentation.rst | 6 ++++++
> 1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> index 391decc66a18..1dd97478743e 100644
> --- a/Documentation/kernel-documentation.rst
> +++ b/Documentation/kernel-documentation.rst
> @@ -370,11 +370,15 @@ To cross-reference the functions and types defined in the kernel-doc comments
> from reStructuredText documents, please use the `Sphinx C Domain`_
> references. For example::
> 
> +.. code-block:: none
> +
>  See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
> 
> While the type reference works with just the type name, without the
> struct/union/enum/typedef part in front, you may want to use::
> 
> +.. code-block:: none
> +
>  See :c:type:`struct foo <foo>`.
>  See :c:type:`union bar <bar>`.
>  See :c:type:`enum baz <baz>`.
> @@ -573,6 +577,8 @@ converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
> enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
> which uses ``pandoc`` under the hood. For example::
> 
> +.. code-block:: none
> +
>  $ cd Documentation/sphinx
>  $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
> 
> -- 
> 2.7.4
> 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Jonathan Corbet]

On Wed, 20 Jul 2016 16:23:28 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Sphinx 1.4.5 complains about some literal blocks at
> > kernel-documentation.rst:
> > 
> > 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> > 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> > 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> > 
> > Fix it by telling Sphinx to consider them as "none" type.  
> 
> Hi Mauro,
> 
> IMHO we should better fix this by unsetting the lexers default language 
> in the conf.py  [1] ... currently:
> 
> highlight_language = 'C'  # set this to 'none'
> 	
> As far as I know the default highlight_language is also the default
> for literal blocks starting with "::"

The thing with that is that a lot of literal blocks *do* have C code, even
in kernel-documentation.rst.  Setting that in conf.py would turn off all C
highlighting.  I think that might actually be a desirable outcome, but it
would be good to make that decision explicitly.

As it happens, I'd already fixed these particular warnings in docs-next:

	http://permalink.gmane.org/gmane.linux.documentation/39806

I took a different approach; using code-block might actually be better.

jon

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 08:31:49 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Wed, 20 Jul 2016 16:23:28 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
> > Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >   
> > > Sphinx 1.4.5 complains about some literal blocks at
> > > kernel-documentation.rst:
> > > 
> > > 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> > > 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> > > 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> > > 
> > > Fix it by telling Sphinx to consider them as "none" type.    
> > 
> > Hi Mauro,
> > 
> > IMHO we should better fix this by unsetting the lexers default language 
> > in the conf.py  [1] ... currently:
> > 
> > highlight_language = 'C'  # set this to 'none'
> > 	
> > As far as I know the default highlight_language is also the default
> > for literal blocks starting with "::"  
> 
> The thing with that is that a lot of literal blocks *do* have C code, even
> in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> highlighting.  I think that might actually be a desirable outcome, but it
> would be good to make that decision explicitly.

Agreed. Assuming "C" as default seems a good idea to me.

> 
> As it happens, I'd already fixed these particular warnings in docs-next:
> 
> 	http://permalink.gmane.org/gmane.linux.documentation/39806
> 
> I took a different approach; using code-block might actually be better.

Particularly, I prefer to explicitly tell when a block has a different
highlight than to switch the default along the document with "highlight"
tag, as this can be trickier to maintain as the document suffers
review along the time.

Anyway, your call ;)

Thanks,
Mauro

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Markus Heiser]

Am 20.07.2016 um 16:31 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Wed, 20 Jul 2016 16:23:28 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> 
>>> Sphinx 1.4.5 complains about some literal blocks at
>>> kernel-documentation.rst:
>>> 
>>> 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>> 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>> 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>> 
>>> Fix it by telling Sphinx to consider them as "none" type.  
>> 
>> Hi Mauro,
>> 
>> IMHO we should better fix this by unsetting the lexers default language 
>> in the conf.py  [1] ... currently:
>> 
>> highlight_language = 'C'  # set this to 'none'
>> 	
>> As far as I know the default highlight_language is also the default
>> for literal blocks starting with "::"
> 
> The thing with that is that a lot of literal blocks *do* have C code, even
> in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> highlighting.  I think that might actually be a desirable outcome, but it
> would be good to make that decision explicitly.
> 
> As it happens, I'd already fixed these particular warnings in docs-next:
> 
> 	http://permalink.gmane.org/gmane.linux.documentation/39806
> 
> I took a different approach; using code-block might actually be better.

In some kernel-doc comments we have constructs like this:

 * host point of view, the graphic address space is partitioned by multiple
 * vGPUs in different VMs.::
 *
 *                        vGPU1 view         Host view
 *             0 ------> +-----------+     +-----------+
 *               ^       |///////////|     |   vGPU3   |
 *               |       |///////////|     +-----------+
 *               |       |///////////|     |   vGPU2   |
 *               |       +-----------+     +-----------+
 *        mappable GM    | available | ==> |   vGPU1   |
 *               |       +-----------+     +-----------+

I mean, in kernel-doc comments it would be nice to have no lexer
active when starting a literal block with a double colon "::".
Introducing a none highlighted literal block with a directive
like ".. highlight::" or ".. code-block" is a bit verbose
for a C comment.  And on the opposite, if one place a C construct
in a literal block with a double colon "::", only the highlighting
is missed, but we get now warning.

At least a code-block should be a code block, not a diagram 
or anything other ...

I don't know whats the best ... but these are my 2cent :)

--Markus--


> 
> jon
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 16:49:59 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 20.07.2016 um 16:31 schrieb Jonathan Corbet <corbet@lwn.net>:
> 
> > On Wed, 20 Jul 2016 16:23:28 +0200
> > Markus Heiser <markus.heiser@darmarit.de> wrote:
> >   
> >> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >>   
> >>> Sphinx 1.4.5 complains about some literal blocks at
> >>> kernel-documentation.rst:
> >>> 
> >>> 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> >>> 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> >>> 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> >>> 
> >>> Fix it by telling Sphinx to consider them as "none" type.    
> >> 
> >> Hi Mauro,
> >> 
> >> IMHO we should better fix this by unsetting the lexers default language 
> >> in the conf.py  [1] ... currently:
> >> 
> >> highlight_language = 'C'  # set this to 'none'
> >> 	
> >> As far as I know the default highlight_language is also the default
> >> for literal blocks starting with "::"  
> > 
> > The thing with that is that a lot of literal blocks *do* have C code, even
> > in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> > highlighting.  I think that might actually be a desirable outcome, but it
> > would be good to make that decision explicitly.
> > 
> > As it happens, I'd already fixed these particular warnings in docs-next:
> > 
> > 	http://permalink.gmane.org/gmane.linux.documentation/39806
> > 
> > I took a different approach; using code-block might actually be better.  
> 
> In some kernel-doc comments we have constructs like this:
> 
>  * host point of view, the graphic address space is partitioned by multiple
>  * vGPUs in different VMs.::
>  *
>  *                        vGPU1 view         Host view
>  *             0 ------> +-----------+     +-----------+
>  *               ^       |///////////|     |   vGPU3   |
>  *               |       |///////////|     +-----------+
>  *               |       |///////////|     |   vGPU2   |
>  *               |       +-----------+     +-----------+
>  *        mappable GM    | available | ==> |   vGPU1   |
>  *               |       +-----------+     +-----------+
> 
> I mean, in kernel-doc comments it would be nice to have no lexer
> active when starting a literal block with a double colon "::".
> Introducing a none highlighted literal block with a directive
> like ".. highlight::" or ".. code-block" is a bit verbose
> for a C comment.  And on the opposite, if one place a C construct
> in a literal block with a double colon "::", only the highlighting
> is missed, but we get now warning.
> 
> At least a code-block should be a code block, not a diagram 
> or anything other ...
> 
> I don't know whats the best ... but these are my 2cent :)

I actually think that the best would be if we could have a way to
"draw" graphs inside the documentation. We have a few cases of
diagrams like the above at the media documentation too.

As Sphinx seems to like ASCIIart, IMHO, the more Sphinx-style
way would be to have a:

.. code-block:: asciiart

markup to handle it.

Another possibility would be to have a graphviz extension.

> 
> --Markus--
> 
> 
> > 
> > jon
> > --
> > To unsubscribe from this list: send the line "unsubscribe linux-media" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html  
> 



Thanks,
Mauro

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Markus Heiser]

Am 20.07.2016 um 17:06 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Em Wed, 20 Jul 2016 16:49:59 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>> Am 20.07.2016 um 16:31 schrieb Jonathan Corbet <corbet@lwn.net>:
>> 
>>> On Wed, 20 Jul 2016 16:23:28 +0200
>>> Markus Heiser <markus.heiser@darmarit.de> wrote:
>>> 
>>>> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>>> 
>>>>> Sphinx 1.4.5 complains about some literal blocks at
>>>>> kernel-documentation.rst:
>>>>> 
>>>>> 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>>>> 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>>>> 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>>>> 
>>>>> Fix it by telling Sphinx to consider them as "none" type.    
>>>> 
>>>> Hi Mauro,
>>>> 
>>>> IMHO we should better fix this by unsetting the lexers default language 
>>>> in the conf.py  [1] ... currently:
>>>> 
>>>> highlight_language = 'C'  # set this to 'none'
>>>> 	
>>>> As far as I know the default highlight_language is also the default
>>>> for literal blocks starting with "::"  
>>> 
>>> The thing with that is that a lot of literal blocks *do* have C code, even
>>> in kernel-documentation.rst.  Setting that in conf.py would turn off all C
>>> highlighting.  I think that might actually be a desirable outcome, but it
>>> would be good to make that decision explicitly.
>>> 
>>> As it happens, I'd already fixed these particular warnings in docs-next:
>>> 
>>> 	http://permalink.gmane.org/gmane.linux.documentation/39806
>>> 
>>> I took a different approach; using code-block might actually be better.  
>> 
>> In some kernel-doc comments we have constructs like this:
>> 
>> * host point of view, the graphic address space is partitioned by multiple
>> * vGPUs in different VMs.::
>> *
>> *                        vGPU1 view         Host view
>> *             0 ------> +-----------+     +-----------+
>> *               ^       |///////////|     |   vGPU3   |
>> *               |       |///////////|     +-----------+
>> *               |       |///////////|     |   vGPU2   |
>> *               |       +-----------+     +-----------+
>> *        mappable GM    | available | ==> |   vGPU1   |
>> *               |       +-----------+     +-----------+
>> 
>> I mean, in kernel-doc comments it would be nice to have no lexer
>> active when starting a literal block with a double colon "::".
>> Introducing a none highlighted literal block with a directive
>> like ".. highlight::" or ".. code-block" is a bit verbose
>> for a C comment.  And on the opposite, if one place a C construct
>> in a literal block with a double colon "::", only the highlighting
>> is missed, but we get now warning.
>> 
>> At least a code-block should be a code block, not a diagram 
>> or anything other ...
>> 
>> I don't know whats the best ... but these are my 2cent :)
> 
> I actually think that the best would be if we could have a way to
> "draw" graphs inside the documentation.

please .. not yet ;-)  ... we have so many problem sites to 
close first ... graphiz & Co. bring additional dependencies
to fulfill in context with sphinx 1.2 ...

> We have a few cases of
> diagrams like the above at the media documentation too.
> 
> As Sphinx seems to like ASCIIart, IMHO, the more Sphinx-style
> way would be to have a:
> 
> .. code-block:: asciiart

> 
> markup to handle it.

why a special markup for a literal block?

-- M --

> Another possibility would be to have a graphviz extension.
> 
>> 
>> --Markus--
>> 
>> 
>>> 
>>> jon
>>> --
>>> To unsubscribe from this list: send the line "unsubscribe linux-media" in
>>> the body of a message to majordomo@vger.kernel.org
>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html  
>> 
> 
> 
> 
> Thanks,
> Mauro
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Jonathan Corbet]

On Wed, 20 Jul 2016 11:41:11 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> > The thing with that is that a lot of literal blocks *do* have C code, even
> > in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> > highlighting.  I think that might actually be a desirable outcome, but it
> > would be good to make that decision explicitly.  
> 
> Agreed. Assuming "C" as default seems a good idea to me.

"Agreed," but there was an implied question there that, I think, deserves
consideration.  Do we want to have a default highlighting language for
literal blocks at all?  Those blocks will contain ascii art diagrams,
device-tree fragments, error message examples, and who knows what else.
Even if the majority of them are C code, having Sphinx treat all of them
as C is going to lead to a steady stream of warnings and a lot of extra
markup in the text.

Plus I'm not convinced that more color eye candy in code fragments is
actually helpful.

So I think I might actually argue in favor of Markus's suggestion and set
the language to "none" by default.  But others may feel strongly about
having their bikeshed in full syntax-highlighted color.  Opinions on the
matter?

Thanks,

jon

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 17:06:41 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Wed, 20 Jul 2016 11:41:11 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > > The thing with that is that a lot of literal blocks *do* have C code, even
> > > in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> > > highlighting.  I think that might actually be a desirable outcome, but it
> > > would be good to make that decision explicitly.    
> > 
> > Agreed. Assuming "C" as default seems a good idea to me.  
> 
> "Agreed," but there was an implied question there that, I think, deserves
> consideration.  Do we want to have a default highlighting language for
> literal blocks at all?  Those blocks will contain ascii art diagrams,
> device-tree fragments, error message examples, and who knows what else.
> Even if the majority of them are C code, having Sphinx treat all of them
> as C is going to lead to a steady stream of warnings and a lot of extra
> markup in the text.

On the documents I edited after the media conversion, I'm explicitly
telling the language (either "c" or "none") on every block. Yet,
any change like that would require to revisit all pages to be sure.
So, changing the default should not cause any change. Yet, I think
that, if we'll be changing the default, the best is to do it as
early as possible.

> Plus I'm not convinced that more color eye candy in code fragments is
> actually helpful.

I use colors on the text editors I use to edit the code and on my
shell prompt. So, I'm suspect, but, at least to me, I prefer it
colored.

Yet, I would very much prefer if, instead of changing the colors for
some random C code, it would be adding hyperlinks to all API calls.
This is what Doxygen does. So, we can include real code examples,
and the user can use them to cross reference with the corresponding
API symbols, like here:
	https://linuxtv.org/docs/libdvbv5/dvbv5-scan_8c-example.html

IMHO, we should mark all C codes as such, and then pursue the goal of
having an extension that would do the same.

> So I think I might actually argue in favor of Markus's suggestion and set
> the language to "none" by default.  But others may feel strongly about
> having their bikeshed in full syntax-highlighted color.  Opinions on the
> matter?
> 
> Thanks,
> 
> jon



Thanks,
Mauro

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 17:33:31 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 20.07.2016 um 17:06 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Em Wed, 20 Jul 2016 16:49:59 +0200
> > Markus Heiser <markus.heiser@darmarit.de> escreveu:
> >   
> >> Am 20.07.2016 um 16:31 schrieb Jonathan Corbet <corbet@lwn.net>:
> >>   
> >>> On Wed, 20 Jul 2016 16:23:28 +0200
> >>> Markus Heiser <markus.heiser@darmarit.de> wrote:
> >>>   
> >>>> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >>>>   
> >>>>> Sphinx 1.4.5 complains about some literal blocks at
> >>>>> kernel-documentation.rst:
> >>>>> 
> >>>>> 	Documentation/kernel-documentation.rst:373: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> >>>>> 	Documentation/kernel-documentation.rst:378: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> >>>>> 	Documentation/kernel-documentation.rst:576: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> >>>>> 
> >>>>> Fix it by telling Sphinx to consider them as "none" type.      
> >>>> 
> >>>> Hi Mauro,
> >>>> 
> >>>> IMHO we should better fix this by unsetting the lexers default language 
> >>>> in the conf.py  [1] ... currently:
> >>>> 
> >>>> highlight_language = 'C'  # set this to 'none'
> >>>> 	
> >>>> As far as I know the default highlight_language is also the default
> >>>> for literal blocks starting with "::"    
> >>> 
> >>> The thing with that is that a lot of literal blocks *do* have C code, even
> >>> in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> >>> highlighting.  I think that might actually be a desirable outcome, but it
> >>> would be good to make that decision explicitly.
> >>> 
> >>> As it happens, I'd already fixed these particular warnings in docs-next:
> >>> 
> >>> 	http://permalink.gmane.org/gmane.linux.documentation/39806
> >>> 
> >>> I took a different approach; using code-block might actually be better.    
> >> 
> >> In some kernel-doc comments we have constructs like this:
> >> 
> >> * host point of view, the graphic address space is partitioned by multiple
> >> * vGPUs in different VMs.::
> >> *
> >> *                        vGPU1 view         Host view
> >> *             0 ------> +-----------+     +-----------+
> >> *               ^       |///////////|     |   vGPU3   |
> >> *               |       |///////////|     +-----------+
> >> *               |       |///////////|     |   vGPU2   |
> >> *               |       +-----------+     +-----------+
> >> *        mappable GM    | available | ==> |   vGPU1   |
> >> *               |       +-----------+     +-----------+
> >> 
> >> I mean, in kernel-doc comments it would be nice to have no lexer
> >> active when starting a literal block with a double colon "::".
> >> Introducing a none highlighted literal block with a directive
> >> like ".. highlight::" or ".. code-block" is a bit verbose
> >> for a C comment.  And on the opposite, if one place a C construct
> >> in a literal block with a double colon "::", only the highlighting
> >> is missed, but we get now warning.
> >> 
> >> At least a code-block should be a code block, not a diagram 
> >> or anything other ...
> >> 
> >> I don't know whats the best ... but these are my 2cent :)  
> > 
> > I actually think that the best would be if we could have a way to
> > "draw" graphs inside the documentation.  
> 
> please .. not yet ;-)  ... we have so many problem sites to 
> close first ... graphiz & Co. bring additional dependencies
> to fulfill in context with sphinx 1.2 ...

Yeah, let's close the other issues first ;)

> 
> > We have a few cases of
> > diagrams like the above at the media documentation too.
> > 
> > As Sphinx seems to like ASCIIart, IMHO, the more Sphinx-style
> > way would be to have a:
> > 
> > .. code-block:: asciiart  
> 
> > 
> > markup to handle it.  
> 
> why a special markup for a literal block?

What I meant to say is to use something that would convert from
asciiart into a picture, just like Sphinx does with tables.

Anyway, this is not a top priority ;)

Thanks,
Mauro