Documenting your API: add highlighted chunk of code in docstrings #5374
Description
Thinking that also highlighted code-blocks were enabled in the dynamic documentation I started to investigate why code-block (also without highlight) not works and at the end I found that there is a strip that remove any kind of indentation, that is bad for code-blocks.
--- schemas_orig.py 2017-08-30 14:45:38.061047196 +0000
+++ schemas.py 2017-08-30 14:46:10.317254482 +0000
@@ -476,7 +476,7 @@
return formatting.dedent(smart_text(method_docstring))
description = view.get_view_description()
- lines = [line.strip() for line in description.splitlines()]
+ lines = [line for line in description.splitlines()]
current_section = ''
sections = {'': ''}
At the end, adding this change and a proper Preprocessor for markdown in the render_markdown function I achieved my goal:
Starting from this docstring:
"""
get:
Return the list of country objects with **iso2**,
**name** and **region** fields.
@@ json @@
[
{
"first": "string-value",
"second": null
},
{
"one": 1,
"two": 2
}
]
@@
"""
I want to submit a PR with this (small) change but before I would know if the line.strip() has a precise meaning and cannot be removed or not.
Thank you, Matteo.