web-dev-qa-db-fra.com

Comment conserver les sauts de ligne lors de la génération de documents python à l'aide de sphinx

J'utilise Sphinx pour générer des documents pour un projet python. Le code HTML de sortie ne conserve pas les sauts de ligne qui sont présents dans la docstring. Exemple:

Code

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

Toute idée de comment résoudre ce problème ?

pythonpython-sphinx
44
Saurabh Saxena

En général, dans l'utilisation de texte restructuré

| Vertical bars
| like this

pour garder les sauts de ligne

42
Owen

Si vous ajoutez ce qui suit à votre fichier .rst principal:

.. |br| raw:: html

   <br />

Ensuite, dans votre balisage, vous pouvez ajouter |br| pour créer des sauts de ligne uniquement pour 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

23
geographika

Cette réponse arrive tard, mais peut-être qu'elle sera toujours utile aux autres.

Vous pouvez utiliser reStructuredText dans vos docstrings. Cela ressemblerait à quelque chose comme

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

D'après l'apparence de votre exemple, il semble que vous utilisez le style Google pour les docstrings ( http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments =).

Sphinx ne les prend pas nativement en charge. Il existe cependant une extension nommée napoleon qui analyse les docstrings de style Google et Numpy à https://pypi.python.org/pypi/sphinxcontrib-napoleon .

Pour utiliser l'extension, vous devez ajouter 'sphinxcontrib.napoleon' à la liste extension- de votre Sphinx conf.py (généralement doc/source/conf.py), donc ça devient quelque chose comme

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

Dans votre cas, vous pouvez écrire:

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

  | Arguments:
  | arg1: arg1 description
  | arg2: arg2 description

  | Returns:
  | None
  """
  print "I am a test method"
9
Francesco

Dans mon cas particulier, j'essayais d'obtenir un autodoc pour lire une chaîne de doc (""" my doc string """). J'ai fini par utiliser \n partout où je devais ajouter un saut de ligne:

This is the first line\n
and this is the second line\n
5
Adam Hammouda

Assurez-vous que votre feuille de style CSS a un remplissage ou des marges sur l'élément p afin que les paragraphes créés par Sphinx soient visibles.

Dans de nombreux cas, les problèmes de rendu peuvent être résolus plus facilement en modifiant la feuille de style plutôt qu'en essayant de contrôler exactement ce que Sphinx génère.

0
Roger Dahl