Difference between revisions of "Sphinx gotchas"

From Software Heritage Wiki
Jump to navigation Jump to search
(add gotcha: verbatim code blocks)
(add gotcha: lists)
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.
  
 +
== Lists ==
 +
 +
All sorts of [http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks lists] require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet
 +
 +
Good:
 +
<pre>
 +
this is some text preceding the list
 +
 +
- foo
 +
- bar
 +
- baz
 +
- this is a rather long-ish paragraph inserted in the list
 +
  with line continuation
 +
- qux
 +
 +
this is some text following the list
 +
</pre>
 +
 +
Bad:
 +
<pre>
 +
this is a bad example that will not be interpreted as a list
 +
preceding text
 +
- foo
 +
- bar
 +
- baz
 +
following text
 +
</pre>
 +
 +
Good:
 +
<pre>
 +
surrounding text
 +
 +
- foo
 +
- nested lists also requires empty lines
 +
 +
  - inner list 1
 +
  - inner list 2
 +
 +
- outer list continues here
 +
 +
surrounding text
 +
</pre>
 +
 +
Bad:
 +
<pre>
 +
- foo
 +
- nested lists also requires empty lines
 +
  - inner list 1
 +
  - inner list 2
 +
- outer list continues here
 +
</pre>
  
 
== Verbatim code blocks ==
 
== Verbatim code blocks ==

Revision as of 13:16, 7 September 2017

Here is a list of common gotchas when formatting Python docstrings for Sphinx and the Napoleon style.

Lists

All sorts of lists require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet

Good:

this is some text preceding the list

- foo
- bar
- baz
- this is a rather long-ish paragraph inserted in the list
  with line continuation
- qux

this is some text following the list

Bad:

this is a bad example that will not be interpreted as a list
preceding text
- foo
- bar
- baz
following text

Good:

surrounding text

- foo
- nested lists also requires empty lines

  - inner list 1
  - inner list 2

- outer list continues here

surrounding text

Bad:

- foo
- nested lists also requires empty lines
  - inner list 1
  - inner list 2
- outer list continues here

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