Как сохранить разрывы строк при создании документов python с использованием sphinx

Я использую 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

Есть идея, как это исправить?

Ответ 1

В общем случае в реструктурированном тексте используйте

| Vertical bars
| like this

чтобы сохранить разрывы строк

Ответ 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

Ответ 3

Этот ответ приходит поздно, но, возможно, он по-прежнему будет полезен другим.

Вы можете использовать reStructuredText в своих документах. Это выглядело бы как

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

Из взглядов вашего примера, однако, похоже, вы используете стиль Google для docstrings (http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments).

Сфинкс не поддерживает их. Однако существует расширение с именем napoleon, которое анализирует docstrings стиля Google и Numpy на https://pypi.python.org/pypi/sphinxcontrib-napoleon.

Чтобы использовать расширение, вы должны добавить 'sphinxcontrib.napoleon' в extension -list в свой Sphinx conf.py (обычно doc/source/conf.py), поэтому он становится чем-то вроде

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

Ответ 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"

Ответ 5

В моем конкретном случае я пытался получить autodoc для чтения строки doc (""" my doc string """). Я закончил использование \n везде, где мне нужно было добавить разрыв строки:

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

Ответ 6

Убедитесь, что ваша таблица стилей CSS имеет отступы или поля в элементе p чтобы абзацы, которые создает Sphinx, были видны.

Во многих случаях проблемы рендеринга могут быть легко устранены путем настройки таблицы стилей, а не путем точного управления тем, что генерирует Sphinx.