How to preserve line breaks when generating python docs using sphinx
In general in restructured text use
| Vertical bars| like this
to keep line breaks
If you add the following to your main .rst file:
.. |br| raw:: html <br />
Then in your markup you can add in |br|
to create linebreaks just for HTML.
I want to break this line here: |br| after the break.
From: http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline
This answer comes late, but maybe it'll still be useful to others.
You could use reStructuredText
in your docstrings. This would look something like
:param arg1: arg1 description:type arg1: str:param arg2: arg2 description:type arg2: str
From the looks of your example however it seems you're using the Google Style for docstrings (http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments).
Sphinx does not natively support those. There is however an extension named napoleon
that parses Google and Numpy style docstrings at https://pypi.python.org/pypi/sphinxcontrib-napoleon.
To use the extension you have to append 'sphinxcontrib.napoleon'
to the extension
-list in your Sphinx conf.py
(usually doc/source/conf.py
), so it becomes something like
extensions = [ 'sphinx.ext.autodoc', 'sphinxcontrib.napoleon', 'sphinx.ext.doctest', ]