如何在使用sphinx生成python文档时保留换行符

Question

我正在使用Sphinx为一个Python项目生成文档。生成的HTML文件没有保留文档字符串中的换行符。举个例子：

代码

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 输出：

TestModule.testMethod(arg1, arg2)

This is a test method

Arguments: arg1: arg1 description arg2: arg2 description

Returns: None

有没有什么办法可以解决这个问题？

Answer 1

这个回答来得有点晚，但希望对其他人还是有用。

你可以在你的文档字符串中使用 reStructuredText 格式。它的样子大概是这样的：

:param arg1: arg1 description
:type arg1: str
:param arg2: arg2 description
:type arg2: str

不过，从你的例子来看，你似乎是在使用谷歌风格的文档字符串（http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments）。

Sphinx 默认不支持这种风格。不过，有一个叫 napoleon 的扩展，它可以解析谷歌和 Numpy 风格的文档字符串，地址在这里：https://pypi.python.org/pypi/sphinxcontrib-napoleon。

要使用这个扩展，你需要把 'sphinxcontrib.napoleon' 加到你的 Sphinx conf.py 文件中的 extension 列表里（通常是在 doc/source/conf.py），这样就变成了：

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

Answer 2

如果你在你的主 .rst 文件中添加以下内容：

.. |br| raw:: html

   <br />

那么在你的标记中，你可以加入 |br| 来专门为 HTML 创建换行。

I want to break this line here: |br| after the break.

来源： http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline

Answer 3

一般来说，在重构文本中使用

| Vertical bars
| like this

可以保持换行效果