example - Cómo preservar los saltos de línea al generar documentos python con sphinx

sphinx search

Question

Estoy usando Sphinx para generar documentos para un proyecto de Python. La salida html no preserva los saltos de línea que están presentes en la docstring. Ejemplo:

Código

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

Alguna de idea de cómo arreglarlo ?

Answer 1

En general, en el uso de texto reestructurado

| Vertical bars
| like this

para mantener saltos de línea

Answer 2

En mi caso particular, estaba tratando de obtener autodoc para leer una cadena de documentación ( """ my doc string """ ). Terminé usando /n todas partes que necesitaba para agregar un salto de línea:

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

Answer 3

En tu caso, puedes escribir:

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 4

Esta respuesta llega tarde, pero tal vez todavía sea útil para otros.

Puede usar reStructuredText en sus documentos. Esto se vería como

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

Sin embargo, a juzgar por el aspecto de su ejemplo, parece que está utilizando Google Style para docstrings ( http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments ).

Sphinx no los admite de forma nativa. Sin embargo, hay una extensión llamada napoleon que analiza las cadenas de documentos de Google y Numpy en https://pypi.python.org/pypi/sphinxcontrib-napoleon .

Para usar la extensión, debe agregar ''sphinxcontrib.napoleon'' a la lista de extension en su Sphinx conf.py (generalmente doc/source/conf.py ), por lo que se convierte en algo así como

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

Answer 5

Si agrega lo siguiente a su archivo principal .rst:

.. |br| raw:: html

   <br />

Luego, en su marcado, puede agregar |br| para crear saltos de línea solo para HTML.

I want to break this line here: |br| after the break.

De: http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline