Modo automatico per passare dalla formattazione di documning di epydoc alla formattazione di sphinx docstring?

Question

Ho un progetto che ho documentato usando epydoc. Ora sto provando a passare alla sfinge. Ho formattato tutte le mie docstring per gli epydoc, usando B {}, L {} ecc per grassetto, linking e simili, e usando @param, @return, @raise ecc per spiegare input, output, eccezioni e simili.

Così ora che sto passando alla sfinge, perde tutte queste caratteristiche. Esiste un modo automatico per convertire docstrings formattati per epydoc in docstrings formattati per sfinge?

Answer 1

Per espandere la risposta di Kevin Horn, le docstring possono essere tradotte al volo in un gestore eventi attivato dall'evento autodoc-process-docstring.

Di seguito è riportata una piccola dimostrazione (provarlo aggiungendo il codice a conf.py). Sostituisce il carattere @ in alcuni comuni Epytext fields con :, che viene utilizzato nel corrispondente Sphinx fields.

import re 

re_field = re.compile('@(param|type|rtype|return)') 

def fix_docstring(app, what, name, obj, options, lines): 
    for i in xrange(len(lines)): 
     lines[i] = re_field.sub(r':\1', lines[i]) 

def setup(app): 
    app.connect('autodoc-process-docstring', fix_docstring) 

Answer 2

In teoria si potrebbe scrivere un'estensione Sfinge che catturerebbe qualsiasi evento venga generato quando una docstring viene letta (source_read, forse?) E traduce le docstring al volo.

dico in teoria perché:

1. ho intenzione di scrivere una cosa del genere per un tempo molto lungo, ma non sono riusciti a ottenere intorno ad esso ancora.
2. Tradurre roba del genere è sempre più difficile di quanto sembri.

Probabilmente potresti anche provare a sostituire tutte le docstrings nel tuo codice con un traduttore simile al di fuori di Sphinx, magari usando il modulo ast o qualcosa di simile.

Answer 3

Pyment è uno strumento che può convertire docstring Python e creare mancanti quelli scheletri. Può gestire Google, Epydoc (stile javadoc), Numpydoc, reStructuredText (riposo, Sfinge di default) Formati docstring.

Accetta un singolo file o una cartella (esplorando anche sottocartelle). Per ogni file, riconoscerà ogni formato docstring e lo convertirà in quello desiderato. Alla fine, verrà generata una patch da applicare al file.

Per convertire il vostro progetto:

• installare Pyment

Digitare il seguente (è possibile utilizzare un virtualenv):

$ git clone https://github.com/dadadel/pyment.git 
$ cd pyment 
$ python setup.py install 

• convertito da Epydoc a Sfinge

È possibile convertire il progetto nel formato Sfinge (il resto), che è il formato di output predefinito, facendo:

$ pyment /my/folder/project