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 ?

Example needed. Restructured text format is correctly preserved by Sphinx. — Mikko Ohtamaa, Aug 11 '11 at 22:00
Any idea on how to do this when your docstrings are in Google format and want to avoid adding a bunch of \n 's ? — Rutger Hofste, Jan 10 '18 at 00:00

score 58 · Answer 1 · answered Aug 11 '11 at 22:22

58

In general in restructured text use

| Vertical bars
| like this

to keep line breaks

answered Aug 11 '11 at 22:22

Owen

38,836
14
95
125

17

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. – Augiwan Jan 15 '13 at 11:49
I believe this break the html semantic. Instead of `
` you end up with `
` ...
– sebastienbarbier May 07 '19 at 07:07
In case, someone is looking for the documentation: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks – Robsdedude Feb 08 '22 at 11:21

score 23 · Answer 2 · edited Sep 29 '12 at 18:35

23

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

edited Sep 29 '12 at 18:35

Gringo Suave

29,931
6
88
75

answered Mar 12 '12 at 09:52

geographika

6,458
4
38
56

1

This works with figure captions, whereas I couldn't get the vertical bars to work. – Dennis Sep 29 '13 at 21:55
3

Beware that the |br| in the text need to be surrounded by spaces. – Thierry J. Jul 03 '15 at 00:55

score 19 · Answer 3 · answered Apr 08 '15 at 11:52

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

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. — Sebastian Höffner, Jul 19 '15 at 04:32
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. — ash84, Oct 29 '15 at 07:10

score 12 · Answer 4 · answered Sep 20 '13 at 15:06

12

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"

answered Sep 20 '13 at 15:06

Francesco

4,052
2
21
29

1

This didn't work for me in Python 3.8 – Sameen Sep 28 '22 at 10:32

score 12 · Answer 5 · edited Nov 09 '12 at 18:55

12

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

edited Nov 09 '12 at 18:55

Martijn Pieters

1,048,767
296
4,058
3,343

answered Oct 11 '11 at 16:10

Adam Hammouda

121
1
2

3

any idea on how to do this when your docstring is in Google Format? – Rutger Hofste Jan 10 '18 at 00:00

score 2 · Answer 6 · answered May 08 '21 at 23:15

2

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

answered May 08 '21 at 23:15

Reza Behzadpour

638
5
16

score 0 · Answer 7 · answered Jul 25 '19 at 04:04

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.

score 0 · Answer 8 · answered Jun 01 '22 at 21:47

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.

score 0 · Answer 9 · answered Jul 22 '23 at 09:56

0

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)

answered Jul 22 '23 at 09:56

Starrow Pan

29
4

How to preserve line breaks when generating python docs using sphinx

9 Answers9

Linked