From c7014b82d930d10e2dc88cd2ab9eb880f78e69c1 Mon Sep 17 00:00:00 2001
From: Philip Chimento for code blocks
Code blocks, i.e. |[ ]|, were converted into
elements, but
would be more appropriate.
In addition, add four spaces to the start of each line in a
element
so that Markdown will recognize it as code and not mangle it. As explained
in a FIXME comment, a better solution would be to reimplement
DocstringScanner using Markdown extensions so that such confusion becomes
impossible.
---
giscanner/docwriter.py | 24 +++++++++++++++++++-----
1 file changed, 19 insertions(+), 5 deletions(-)
diff --git a/giscanner/docwriter.py b/giscanner/docwriter.py
index cba8a5d8..d17e8700 100644
--- a/giscanner/docwriter.py
+++ b/giscanner/docwriter.py
@@ -341,27 +341,41 @@ class DocFormatter(object):
return self.format_xref(func)
+ # FIXME: the four spaces after newlines in the following functions are to
+ # keep Markdown happy. We pass the documentation string first through this
+ # templated scanner, which converts |[ ]| to . Then in the case
+ # of DevDocs output, we pass the resulting string through Markdown; but
+ # Markdown will not respect the
element and will treat the code as
+ # markup, converting asterisks into etc. Putting four spaces at the
+ # start of each line makes Markdown recognize the code as code without
+ # affecting the normal HTML output too much.
+ #
+ # A better solution would be to replace DocstringScanner by Markdown
+ # entirely, implementing the custom markup with Markdown extensions.
+
def _process_code_start(self, node, match, props):
self._processing_code = True
- return "
"
+ return '\n '
def _process_code_start_with_language(self, node, match, props):
mime = language_mimes[props["language_name"].lower()]
self._processing_code = True
if not mime:
- return ""
- return ''
+ return '\n '
+ return '\n '
def _process_code_end(self, node, match, props):
self._processing_code = False
- return "
"
+ return '\n
'
def _process_new_line(self, node, match, props):
+ if self._processing_code:
+ return '\n '
return '\n'
def _process_new_paragraph(self, node, match, props):
if self._processing_code:
- return '\n\n'
+ return '\n\n '
return "
"
def _process_token(self, node, tok):
--
cgit v1.2.1