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 ?

Waldon

Example needed. Restructured text format is correctly preserved by Sphinx. – Analeptic

Any idea on how to do this when your docstrings are in Google format and want to avoid adding a bunch of \n 's ? – Faye

Answer 1

In general in restructured text use

| Vertical bars
| like this

to keep line breaks

Josefjosefa

Don't just add | on two separate lines (say if you want two line breaks)... make sure you have 2 empty spaces after the | So it becomes: |(space)(space) for a new line. – Empress

I believe this break the html semantic. Instead of <p> you end up with <div class="line"> ... – Moreta

In case, someone is looking for the documentation: docutils.sourceforge.io/docs/ref/rst/… – Odlo

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

Cowden

This works with figure captions, whereas I couldn't get the vertical bars to work. – Weisbrodt

Beware that the |br| in the text need to be surrounded by spaces. – Striate

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

Stlouis

This was the exact answer I was looking for while trying to understand why sphinx wouldn't render the Google Style correclty although the guide lines even recommend to use Sphinx. – Montagu

As of Sphinx 1.3, the napoleon extension will come packaged with Sphinx under sphinx.ext.napoleon. The sphinxcontrib.napoleon extension will continue to work with Sphinx <= 1.2. – Hurlyburly

Answer 4

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

Yehudi

any idea on how to do this when your docstring is in Google Format? – Faye

Answer 5

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"

Barramunda

This didn't work for me in Python 3.8 – Pardoner

Answer 6

See if you have enabled Support for NumPy and Google style docstrings extension in your conf.py file:

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

Detest

Answer 7

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.

Roentgen

Answer 8

I am NOT using Sphinx, and none of these answers worked for me.

I finally found the answer here.

You just need to put \b alone on a line before the paragraph. For example,

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

    \b
    Arguments:
    arg1: arg1 description
    arg2: arg2 description

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

The \b bizarrely is actually a backspace character.

Expiate

Answer 9

The vertical bars doesn't work for me. I use the following format instead.

::
    Straight Flush: (8, high card)
    Four of a Kind: (7, quad card)

Septuor