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"

Sphinx 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本身并不支持这些。但是有一个名为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

在你的情况下你可以写：

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

Answer 6

请确保您的CSS样式表在p元素上具有填充或边距，以使Sphinx创建的段落可见。

在许多情况下，通过调整样式表，比尝试完全控制Sphinx生成的内容更容易解决渲染问题。

Answer 7

查看您是否在 conf.py 文件中启用了 Support for NumPy and Google style docstrings 扩展：

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

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

7 个答案: