Как сохранить разрывы строк при генерации документов Python с использованием sphinx - PullRequest
Новая
       5

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

44 голосов
/ 12 августа 2011

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

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

Ответы [ 5 ]

41 голосов
/ 12 августа 2011

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

| Vertical bars
| like this

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

22 голосов
/ 12 марта 2012

Если вы добавите следующее в ваш основной .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

14 голосов
/ 08 апреля 2015

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

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

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

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

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

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

extensions = [                                                                  
'sphinx.ext.autodoc',                                                       
'sphinxcontrib.napoleon',                                                   
'sphinx.ext.doctest',                                                                                                             
]
9 голосов
/ 20 сентября 2013

В вашем случае вы можете написать: 

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 голосов
/ 11 октября 2011

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

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