How to preserve line breaks when generating python docs using sphinx

Question

I am using Sphinx for generating docs for a python project. The output html is not preserving the line breaks which are present in the docstring. Example:

Code

Answer 1

In your case you can write:

def testMethod(arg1,arg2):
  """
  This is a test method

  | Arguments:
  | arg1: arg1 description
  | arg2: arg2 description

  | Returns:
  | None
  """
  print "I am a test method"

Answer 2

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

Answer 3

In my particular case, I was trying to get autodoc to read a doc string (""" my doc string """). I ended up using \n everywhere I needed to add a line break:

This is the first line\n
and this is the second line\n

Answer 4

In general in restructured text use

| Vertical bars
| like this

to keep line breaks

Answer 5

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',                                                                                                             
]

Answer 6

Make sure that your CSS stylesheet has padding or margins on the p element so that the paragraphs that Sphinx creates are visible.

In many cases, rendering issues can be fixed more easily by tweaking the stylesheet than trying to control exactly what Sphinx generates.