Esistono alternative reali a reStructuredText per la documentazione di Python?

Question

Sto avviando un progetto Python open source a breve e sto cercando di decidere in anticipo come scrivere le mie docstring. La risposta ovvia sarebbe utilizzare reStructuredText e Sphinx con autodoc, perché I in realtà mi piace l'idea di documentare semplicemente correttamente il mio codice nelle mie docstring, quindi Sphinx costruisce automaticamente un documento API per me.

Il problema è la sintassi reStructuredText che utilizza: penso che sia completamente illeggibile prima del rendering. Per esempio:

 
:param path: The path of the file to wrap 
:type path: str 
:param field_storage: The :class:`FileStorage` instance to wrap 
:type field_storage: FileStorage 
:param temporary: Whether or not to delete the file when the File instance 
    is destructed 
:type temporary: bool 

Devi davvero rallentare e prendere un minuto per dare un senso di quel guazzabuglio sintattica. Mi piace molto di più il modo in cui Google (Google Python Style Guide), che omologo a quanto sopra appare così:

 
Args: 
    path (str): The path of the file to wrap 
    field_storage (FileStorage): The FileStorage instance to wrap 
    temporary (bool): Whether or not to delete the file when the File 
     instance is destructed 

Way più bello! Ma, naturalmente, Sphinx non avrà nulla di tutto ciò e renderà tutto il testo dopo "Args:" in una lunga riga.

Quindi, per riassumere - prima di andare a defilare il mio codice base con questa sintassi reStructuredText vorrei sapere se ci sono delle vere alternative per usarlo e Sphinx, a meno di scrivere solo il mio documento API. Ad esempio, esiste un'estensione per Sphinx che gestisce lo stile di docstring di Google Style Guide?

Answer 1

Non penso che ci sia qualcosa di meglio di sphinx per documentare progetti Python al momento.

Per avere una docstring più chiara, la mia scelta preferita è l'utilizzo di sphinx insieme a numpydoc. Sulla base della vostra esempio, questo sarebbe simile:

def foo(path, field_storage, temporary): 
    """This is function foo 

    Parameters 
    ---------- 
    path : str 
     The path of the file to wrap 
    field_storage : :class:`FileStorage` 
     The :class:`FileStorage` instance to wrap 
    temporary : bool 
     Whether or not to delete the file when the File instance 
     is destructed 

    Returns 
    ------- 
    describe : type 
     Explanation 
    ... 

    Examples 
    -------- 
    These are written in doctest format, and should illustrate how to 
    use the function. 

    >>> a=[1,2,3] 
    >>> print [x + 3 for x in a] 
    [4, 5, 6] 
    ... 
    """ 

    pass 

(un esempio completo è Here), output HTML sarà simile this

Credo che la struttura del primo file è più chiaro e leggibile. Il guide fornisce ulteriori informazioni e convenzioni. L'estensione numpydoc funziona anche con autodoc.

Answer 2

Python rende disponibile il contenuto delle docstring come attributo __doc__ associato alla funzione/classe/oggetto variabile.

Quindi, potresti banalmente scrivere un programma Python che converte la documentazione da qualsiasi formato desideri in qualsiasi formato tu voglia. Si potrebbe anche usare lo stile di Javadoc, o XML, o qualsiasi altra cosa.

Per inciso, dal momento che la Sfinge è scritta in Python, facendolo prendere input non RST è solo questione di scrivere una piccola quantità di codice Python.

Answer 3

In realtà, e la guida di stile da PEP8 si applicano principalmente per la codifica della libreria standard Python stessa, anche se molti programmatori di terze parti sono conformi anche a questo.

Sono d'accordo con voi sul fatto che lo stile per argomenti di Google è molto meglio da una prospettiva in-code. Ma dovresti essere in grado di generate such docstring with sphinx, with the new lines and indentation preserved. Non è così bello come with a more sphinxy formatting.

In ogni caso, non è dover uso sfinge, e tra l'altro, il modulo autodoc della Sfinge è sicuramente solo una piccola parte di esso. È possibile utilizzare virtualmente qualsiasi generatore di documentazione che sia in grado di recuperare il contenuto di docstrings, come Epydoc (che supporta epytext e reStructuredText, Javadoc or Plaintext) o pydoctor o anche uno più universale come Doxygen.

Ma sicuramente, la sfinge è piuttosto pythonic, molto comoda da usare con Python e rendere il codice coerente con l'ecosistema di Python. Penso che tu sia not the only one e pensi che questa sia una "mancanza". Forse prenderanno in considerazione questi reclami in futuro, o forse potreste anche considerare di modificare il modulo autodoc da soli, non dovrebbe essere molto difficile, è in Python, sarebbe un buon esercizio.

Answer 4

È possibile scrivere docstrings in qualsiasi formato che ti piace. Tuttavia, per il bene di ogni altro programmatore Python, è meglio usare markup e strumenti che già conoscono. Le loro vite sono più facili se ti attacchi a reST e Sfinge.

Answer 5

Io uso epydoc e non la sfinge, quindi questa risposta potrebbe non essere applicabile.

La sintassi reStructuredText che si descrive per la documentazione dei metodi e delle funzioni non è l'unica possibile. Di gran lunga, preferisco che descrive i parametri utilizzando un consolidated definition list, che è molto simile al modo in cui Google:

:Parameters: 
    path : str 
    The path of the file to wrap 
    field_storage: FileStorage 
    The FileStorage instance to wrap 
    temporary: bool 
    Whether or not to delete the file when the File instance is destructed 

vorrei provare se sphix lo supporta. Se così non fosse, potresti anche prendere in considerazione l'idea di usare l'epydoc solo per quello (anche se non è così attivamente mantenuto in questo momento).

Answer 6

è sufficiente iniziare una nuova riga e aggiungere un tocco dopo ogni nome di variabile. Poi si è reso in diverse linee con i nomi delle variabili in grassetto consucutive:

Args: 
    path (str): 
     The path of the file to wrap 
    field_storage (FileStorage): 
     The FileStorage instance to wrap 
    temporary (bool): 
     Whether or not to delete the file when the File 
     instance is destructed 

Answer 7

ho creato un Sphinx extension che analizza sia in stile Google e docstring stile NumPy, e li converte in reStructuredText standard.

Per utilizzarlo, è sufficiente installarlo:

$ pip install sphinxcontrib-napoleon 

E abilitarlo in conf.py:

# conf.py 

# Add autodoc and napoleon to the extensions list 
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] 

Altro documentazione su napoleon here.