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

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

    Arguments:
    arg1: arg1 description
    arg2: arg2 description

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

Sphinx O/P:

TestModule.testMethod(arg1, arg2)

This is a test method

Arguments: arg1: arg1 description arg2: arg2 description

Returns: None

Any idea how to fix it ?

Solution 1

In general in restructured text use

| Vertical bars
| like this

to keep line breaks

Solution 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

Solution 3

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

Solution 4

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"

Solution 5

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

View more solutions