Jak zachować podział wiersza podczas generowania dokumentacji Pythona przy użyciu Sphinx

Question

Używam Sphinx do generowania dokumentów dla projektu Pythona. Wyjściowy html nie zachowuje podziałów linii, które są obecne w docstringu. Przykład:

Kod

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 

Każdy pomysł jak to naprawić?

Answer 1

Ogólnie w restructuredtext używać

| Vertical bars 
| like this 

zachować linię łamie

Answer 2

W moim przypadku, ja starałem się dostać autodoktora czytać ciąg doc (""" my doc string """). I skończył przy użyciu \n wszędzie Musiałem dodać podział wiersza:

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

Answer 3

Jeśli dodać następujące wpisy do pliku głównego .rst:

.. |br| raw:: html 

    <br /> 

Następnie w znacznikach można dodać w celu |br| tworzyć linebreaks tylko dla HTML.

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

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

Answer 4

W twoim przypadku można napisać:

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

Ta odpowiedź przychodzi późno, ale być może będzie ona nadal być przydatne dla innych.

Możesz użyć reStructuredText w swoich docstrings. To coś będzie wyglądać

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

od spojrzeń swoim przykładzie jednak wydaje się, że używasz stylu Google dla docstrings (http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments).

Sfinks natywnie nie obsługuje tych. Istnieje jednak rozszerzenie o nazwie napoleon, które analizuje nagłówki Google i Numpy pod numerem https://pypi.python.org/pypi/sphinxcontrib-napoleon.

Aby użyć rozszerzenia trzeba dołączyć 'sphinxcontrib.napoleon' do extension -list w Sfinksa conf.py (zwykle doc/source/conf.py), więc staje się coś podobnego

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