使用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"

狮身人面像 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 样式作为文档字符串（http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments）。

Sphinx 本身并不支持这些。然而，有一个名为

napoleon

的扩展可以在 https://pypi.python.org/pypi/sphinxcontrib-napoleon 处解析 Google 和 Numpy 风格的文档字符串。

要使用扩展，您必须将

'sphinxcontrib.napoleon'

附加到 Sphinx

extension

中的

conf.py

列表（通常为

doc/source/conf.py

），所以它会变成类似

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

Answer 4

在我的特定情况下，我试图让 autodoc 读取文档字符串（

""" my doc string """

）。 我最终在需要添加换行符的地方使用了

\n

：

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

Answer 5

根据您的情况，您可以写：

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 6

查看您是否在 conf.py 文件中启用了 支持 NumPy 和 Google 风格文档字符串

扩展：

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

Answer 7

确保您的 CSS 样式表在

p

元素上有填充或边距，以便 Sphinx 创建的段落可见。

在许多情况下，通过调整样式表可以更轻松地解决渲染问题，而不是尝试精确控制 Sphinx 生成的内容。

Answer 8

我不使用Sphinx，这些答案都不适合我。

我终于在这里找到了答案。

您只需将

\b

单独放在段落之前的一行上即可。 例如，

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"

奇怪的是，

\b

实际上是一个

backspace

角色。

Answer 9

竖线对我不起作用。 我使用以下格式代替。

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

Answer 10

对我来说以下工作有效：

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

    Arguments:
        arg1: arg1 description \n
        arg2: arg2 description \n

    Returns:
        None
    """

使用：（空格）