From 39315985e89e6ef3e7c01e697faf439280045157 Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Mon, 22 Oct 2018 10:52:40 +0200 Subject: [PATCH] Documentation: Fix markdown inline code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit recommonmark doesn't know about inline code, while all other software generating documentation is able to handle it. Add support for inline code by adding a wrapper class around the recommonmark parser that converts code to docutils literal blocks. Fixes invisible inline code in current documentation. Change-Id: I0269d15a685ed0c0241be8c8acfade0e58363845 Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/29206 Tested-by: build bot (Jenkins) Reviewed-by: Paul Menzel Reviewed-by: Jonathan Neuschäfer Reviewed-by: Philipp Deppenwiese --- Documentation/conf.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 07868faece..85df9ea51e 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -1,5 +1,6 @@ # -*- coding: utf-8 -*- import subprocess +from recommonmark.parser import CommonMarkParser # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -156,9 +157,14 @@ texinfo_documents = [ 'Miscellaneous'), ] -source_parsers = { - '.md': 'recommonmark.parser.CommonMarkParser', -} +enable_auto_toc_tree = True + +class MyCommonMarkParser(CommonMarkParser): + # remove this hack once upsteam RecommonMark supports inline code + def visit_code(self, mdnode): + from docutils import nodes + n = nodes.literal(mdnode.literal, mdnode.literal) + self.current_node.append(n) # Documents to append as an appendix to all manuals. # @@ -176,11 +182,11 @@ source_parsers = { # # texinfo_no_detailmenu = False -enable_auto_toc_tree = True - def setup(app): from recommonmark.transform import AutoStructify + app.add_source_parser('.md', MyCommonMarkParser) + app.add_config_value('recommonmark_config', { 'enable_auto_toc_tree': True, 'enable_auto_doc_ref': False, # broken in Sphinx 1.6+