From: Jani Nikula Date: Thu, 3 Nov 2016 08:26:54 +0000 (+0200) Subject: Documentation/sphinx: set literal block highlight language to none X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=b459106ea4b7f317faa24b47e9a6b20c2f254d2d;p=GitHub%2Fmoto-9609%2Fandroid_kernel_motorola_exynos9610.git Documentation/sphinx: set literal block highlight language to none Set the default highlight language to "none", i.e. do not try to guess the language and do automatic syntax highlighting on literal blocks. Eyeballing around the generated documentation, we don't seem to actually have a lot of literal blocks that would benefit from syntax highlighting. The C code blocks we do have are typically very short, and most of the literal blocks are things that shouldn't be highlighted (or, do not have a pygments lexer). This seems to be true for literal blocks both in the rst source files and in source code comments. Not highlighting code is never wrong, but guessing the language wrong almost invariably leads to silly or confusing highlighting. At the time of writing, admin-guide/oops-tracing.rst and admin-guide/ramoops.rst contain good examples of 1) a small C code snippet not highlighted, 2) a hex dump highligted as who knows what, 3) device tree block highlighted as C or maybe Python, 4) a terminal interaction highlighted as code in some language, and finally, 5) some C code snippets correctly identified as C. I think we're better off disabling language guessing, and going by explicitly identified languages for longer code blocks. It is still possible to enable highlighting on an rst source file basis using the highlight directive: .. higlight:: language and on a literal block basis using the code-block directive: .. code-block:: language See http://www.sphinx-doc.org/en/latest/markup/code.html for details. Cc: Jonathan Corbet Cc: Mauro Carvalho Chehab Cc: Markus Heiser Signed-off-by: Jani Nikula --- diff --git a/Documentation/conf.py b/Documentation/conf.py index 7830051b6837..bcb1af786e78 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -136,7 +136,7 @@ pygments_style = 'sphinx' todo_include_todos = False primary_domain = 'C' -highlight_language = 'guess' +highlight_language = 'none' # -- Options for HTML output ----------------------------------------------