summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
diff options
context:
space:
mode:
authorJani Nikula <jani.nikula@intel.com>2016-11-03 10:26:54 +0200
committerJani Nikula <jani.nikula@intel.com>2016-11-03 12:38:47 +0200
commitb459106ea4b7f317faa24b47e9a6b20c2f254d2d (patch)
tree919d097f9f3ae6129b15a9c01a6ae8bfde767720 /Documentation/conf.py
parent8d26d90ba3e1cfb75c4af2882045ca2c8120fbab (diff)
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 <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Cc: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Diffstat (limited to 'Documentation/conf.py')
-rw-r--r--Documentation/conf.py2
1 files changed, 1 insertions, 1 deletions
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 ----------------------------------------------