• Jani Nikula's avatar
    Documentation/sphinx: set literal block highlight language to none · b459106e
    Jani Nikula authored
    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: default avatarJani Nikula <jani.nikula@intel.com>
    b459106e
conf.py 16.3 KB