On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > > Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@xxxxxxxx>: > >> 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. Yes I'm aware that sphinx it's WARNINGs when doing a partially rebuild, this is something entirely different. I didn't get more or less warnings this way, but keep_warning = True seems to be the only way to get reasonable information about them. Without that I get warnings (for included kernel-doc) where the source file is the .rst file that pulls in the kernel doc, and the line number is entirely bogus (often past the end of the containing .rst). With this I can at least then open the generated .html file, search for the System Message and figure out (by looking at the surrounding context) where the error really is from. Strangely this only happens for WARNING. If I manged the kerneldoc enough to upset sphinx into generating an ERROR, the line numbers and source files are correct. See patch 2/2 in this series for examples of such WARNINGs: Mostly it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit. If you want to play around with the gpu sphinx conversion to reproduce these locall you can grab the drm-intel-nightly branch from https://cgit.freedesktop.org/drm-intel It already includes Jon's latest docs-next branch. Cheers, Daniel > > -- Markus -- >> >> Cc: Markus Heiser <markus.heiser@xxxxxxxxxxx> >> Cc: Jonathan Corbet <corbet@xxxxxxx> >> Cc: linux-doc@xxxxxxxxxxxxxxx >> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> >> --- >> 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 >> > -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
