Difference between revisions of "Sphinx gotchas"
m (StefanoZacchiroli moved page Python style guide/Sphinx gotchas to Sphinx gotchas without leaving a redirect) |
(add gotcha: verbatim code blocks) |
||
| Line 1: | Line 1: | ||
Here is a list of common gotchas when formatting Python docstrings for [http://www.sphinx-doc.org/en/stable/ Sphinx] and the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon] style. | Here is a list of common gotchas when formatting Python docstrings for [http://www.sphinx-doc.org/en/stable/ Sphinx] and the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon] style. | ||
| − | + | ||
| + | == Verbatim code blocks == | ||
| + | |||
| + | [http://www.sphinx-doc.org/en/stable/rest.html#source-code Verbatim code blocks], e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented: | ||
| + | |||
| + | <pre> | ||
| + | a nice example of python code follows:: | ||
| + | |||
| + | def foo(bar, baz): | ||
| + | qux = bar + baz | ||
| + | |||
| + | return qux | ||
| + | |||
| + | here we can restart text flow | ||
| + | </pre> | ||
[[Category:Guidelines]] | [[Category:Guidelines]] | ||
[[Category:Software development]] | [[Category:Software development]] | ||
[[Category:Python]] | [[Category:Python]] | ||
Revision as of 13:11, 7 September 2017
Here is a list of common gotchas when formatting Python docstrings for Sphinx and the Napoleon style.
Verbatim code blocks
Verbatim code blocks, e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented:
a nice example of python code follows::
def foo(bar, baz):
qux = bar + baz
return qux
here we can restart text flow
