Difference between revisions of "Sphinx gotchas"

From Software Heritage Wiki
Jump to navigation Jump to search
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.
  
'''TODO'''
+
 
 +
== 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