[PATCH 1/2] doc/sphinx: Enable keep_warnings

[Markus Heiser]

Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter at ffwll.ch>:

> Unfortunately warnings generated after parsing in sphinx can end up
> with entirely bogus files and line numbers as sources. Strangely for
> outright errors this is not a problem. Trying to convert warnings to
> errors also doesn't fix it.
> 
> The only way to get useful output out of sphinx to be able to root
> cause the error seems to be enabling keep_warnings, which inserts
> a System Message into the actual output. Not pretty at all, but I
> don't really want to fix up core rst/sphinx code, and this gets the job
> done meanwhile.

Hi Daniel,

may I misunderstood you. Did you really get more or different warnings
if you include them into the output with "keep_warnings"?

The documentation says:

  "Regardless of this setting, warnings are always written
   to the standard error stream when sphinx-build is run."

see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings

Or did you not run "make cleandoc" first? Sphinx caches the doctrees
and reports markup errors only when you rebuild the cache.
The cache is also rebuild if you touch one of the source, e.g.
the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
is referred by a kernel-doc directive .. these dependence sometimes
confuse me .. when I missed log messages, I clean the cache e.g. by 
target cleandocs.

-- Markus --
> 
> Cc: Markus Heiser <markus.heiser at darmarit.de>
> Cc: Jonathan Corbet <corbet at lwn.net>
> Cc: linux-doc at vger.kernel.org
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
> Documentation/conf.py | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 6cc41a0555a3..a131139675cc 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
>