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

Question

我正在使用Sphinx为python项目生成文档.输出html不保留docstring中存在的换行符.例:

码

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

    Arguments:
    arg1: arg1 description
    arg2: arg2 description

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

狮身人面像O/P:

TestModule.testMethod(arg1, arg2)

This is a test method

Arguments: arg1: arg1 description arg2: arg2 description

Returns: None

知道怎么解决吗？

Answer 1

一般来说,在重组文本中使用

| Vertical bars
| like this

保持换行符

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

这个答案来得晚,但也许对其他人来说仍然有用.

您可以reStructuredText在文档字符串中使用.这看起来像

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

从您示例的外观来看,您似乎正在使用Google Style for docstrings(http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments).

Sphinx本身并不支持这些.然而,有一个扩展名为https://pypi.python.org/pypi/sphinxcontrib-napoleonnapoleon解析Google和Numpy风格的文档字符串.

要使用扩展名,你必须附加'sphinxcontrib.napoleon'到extensionSphinx中的-list conf.py(通常doc/source/conf.py),所以它就像是

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

Answer 4

在你的情况下你可以写:

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 5

在我的特定情况下,我试图让autodoc读取文档字符串(""" my doc string """).我最终使用了\n我需要添加换行符的所有地方:

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