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

Groups > linux.kernel > #1457894 > unrolled thread

[PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings""

Back to article view | Back to linux.kernel

Contents

  [PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings"" Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-08-08 18:30 +0200
    Re: [PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings"" Jonathan Corbet <corbet@lwn.net> - 2016-08-08 23:40 +0200
      Re: [PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings"" Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-08-09 16:00 +0200
        Re: [PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings"" Jonathan Corbet <corbet@lwn.net> - 2016-08-09 16:10 +0200
          Re: [PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings"" Markus Heiser <markus.heiser@darmarit.de> - 2016-08-09 16:20 +0200

#1457894 — [PATCH] Revert "Revert "doc/sphinx: Enable keep_warnings""

This reverts commit 29310a50752de76314f51555b72044d11f6cba49.

Even with Markus fixes to the importer I still get warnigns from
sphinx which are entirely bogus :(

/home/daniel/linux/src/Documentation/gpu/drm-kms.rst:13: WARNING: Could not lex literal_block as "C". Highlighting skipped.
/home/daniel/linux/src/Documentation/gpu/drm-kms-helpers.rst:16: WARNING: Could not lex literal_block as "C". Highlighting skipped.
/home/daniel/linux/src/Documentation/gpu/i915.rst:57: WARNING: Could not lex literal_block as "C". Highlighting skipped.

Well it's worse: Those are warnings which don't even show up with this
enabled. Just sending this out again in the hopes some has a clue
what's going on.

Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Markus Heiser <markus.heiser@darmarIT.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 96b7aa66c89c..b6f6761db5e0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -125,7 +125,7 @@ pygments_style = 'sphinx'
 #modindex_common_prefix = []
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+keep_warnings = True
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
-- 
2.8.1

[toc] | [next] | [standalone]

#1458259

On Mon,  8 Aug 2016 18:23:11 +0200
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> Even with Markus fixes to the importer I still get warnigns from
> sphinx which are entirely bogus :(
> 
> /home/daniel/linux/src/Documentation/gpu/drm-kms.rst:13: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> /home/daniel/linux/src/Documentation/gpu/drm-kms-helpers.rst:16: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> /home/daniel/linux/src/Documentation/gpu/i915.rst:57: WARNING: Could not lex literal_block as "C". Highlighting skipped.
> 
> Well it's worse: Those are warnings which don't even show up with this
> enabled. Just sending this out again in the hopes some has a clue
> what's going on.

So I honestly think we should just set the highlight language to "none" by
default.  The syntax highlighting in code samples adds some colorful sugar
to the docs, but it's not really all that useful, IMO, and people who want
it can override the language in the right places.

Any strong opposition to this idea?

jon

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

#1458774

On Mon, Aug 8, 2016 at 11:32 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Mon,  8 Aug 2016 18:23:11 +0200
> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>
>> Even with Markus fixes to the importer I still get warnigns from
>> sphinx which are entirely bogus :(
>>
>> /home/daniel/linux/src/Documentation/gpu/drm-kms.rst:13: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>> /home/daniel/linux/src/Documentation/gpu/drm-kms-helpers.rst:16: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>> /home/daniel/linux/src/Documentation/gpu/i915.rst:57: WARNING: Could not lex literal_block as "C". Highlighting skipped.
>>
>> Well it's worse: Those are warnings which don't even show up with this
>> enabled. Just sending this out again in the hopes some has a clue
>> what's going on.
>
> So I honestly think we should just set the highlight language to "none" by
> default.  The syntax highlighting in code samples adds some colorful sugar
> to the docs, but it's not really all that useful, IMO, and people who want
> it can override the language in the right places.
>
> Any strong opposition to this idea?

Hm right, didn't realize that this is where it's coming from. No
strong opinion from my side on highlighting the C block quotes really.
Otoh that highlighting is rather pretty. Could we perhaps just shut
sphinx up about the "C" highlighting issues?
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

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

#1458785

On Tue, 9 Aug 2016 15:56:15 +0200
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> > So I honestly think we should just set the highlight language to "none" by
> > default.  The syntax highlighting in code samples adds some colorful sugar
> > to the docs, but it's not really all that useful, IMO, and people who want
> > it can override the language in the right places.
> >
> > Any strong opposition to this idea?  
> 
> Hm right, didn't realize that this is where it's coming from. No
> strong opinion from my side on highlighting the C block quotes really.
> Otoh that highlighting is rather pretty. Could we perhaps just shut
> sphinx up about the "C" highlighting issues?

We can look into that, but, in the end, we'll always have a lot of literal
blocks that are not C code.  Even if Sphinx doesn't warn about them, it
tries to mark them up as C with occasionally strange results.  I'm not
really convinced it's a net win.

jon

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

#1458791

Am 09.08.2016 um 16:07 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Tue, 9 Aug 2016 15:56:15 +0200
> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> 
>>> So I honestly think we should just set the highlight language to "none" by
>>> default.  The syntax highlighting in code samples adds some colorful sugar
>>> to the docs, but it's not really all that useful, IMO, and people who want
>>> it can override the language in the right places.
>>> 
>>> Any strong opposition to this idea?  
>> 
>> Hm right, didn't realize that this is where it's coming from. No
>> strong opinion from my side on highlighting the C block quotes really.
>> Otoh that highlighting is rather pretty. Could we perhaps just shut
>> sphinx up about the "C" highlighting issues?
> 
> We can look into that, but, in the end, we'll always have a lot of literal
> blocks that are not C code.  Even if Sphinx doesn't warn about them, it
> tries to mark them up as C with occasionally strange results.  I'm not
> really convinced it's a net win.
> 
> jon

Hi, as far as I know, there is no option to suppress warnings
from the lexer [1]. What's about "highlight_language = 'guess'" ...
I compiled gpu and the warnings disappear, but I have not yet
looked at the complete results in HTML.

[1] FYI: Sphinx's lexer is http://pygments.org/

--M--

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web