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

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

[Daniel Vetter]

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

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

[Jonathan Corbet]

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

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

[Daniel Vetter]

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

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

[Jonathan Corbet]

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

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

[Markus Heiser]

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