¿Forma automatizada de cambiar del formato de docstring de epydoc al formato de docstring de sphinx?

Question

Tengo un proyecto que documenté usando epydoc. Ahora estoy tratando de cambiar a esfinge. He formateado todas mis cadenas de documentos para epydocs, usando B {}, L {} etc. para negrita, enlaces y similares, y usando @param, @return, @raise, etc. para explicar entrada, salida, excepciones y me gusta.

Así que ahora que estoy cambiando a esfinge, pierde todas estas características. ¿Existe una forma automática de convertir docstrings formateadas para epydocs a docstrings formateadas para sphinx?

Answer 1

Para ampliar la respuesta de Kevin Horn, las cadenas de documentos se pueden traducir sobre la marcha en un controlador de eventos desencadenado por el evento autodoc-process-docstring.

A continuación se muestra una pequeña demostración (pruébelo agregando el código a conf.py). Sustituye el carácter @ en algunos Epytext fields comunes con :, que se utiliza en el Sphinx fields correspondiente.

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

En teoría, podría escribir una extensión de Sphinx que captaría cualquier evento que se active cuando se lea una docstring (source_read, ¿no?) Y traduzca las cadenas de documentos sobre la marcha.

que digo en teoría porque:

1. que he estado queriendo escribir una cosa así durante mucho tiempo, pero no han logrado conseguir alrededor de él todavía.
2. Traducir cosas como esta siempre es más difícil de lo que parece.

Usted podría también, probablemente, tratar sólo la sustitución de todas las cadenas de documentación en el código con un traductor similar fuera de la Esfinge, tal vez usando el módulo ast o algo similar.

Answer 3

Pyment es una herramienta que puede convertir cadenas de documentación de Python y crear faltan queridos esqueletos. Puede gestionar Google, Epydoc (estilo javadoc), Numpydoc, reStructuredText (descanso, por defecto) Sphinx formatos cadena de documentación.

Acepta un solo archivo o una carpeta (explorando también las subcarpetas). Para cada archivo, reconocerá cada formato de docstring y lo convertirá al formato deseado. Al final, se generará un parche para aplicar al archivo.

para convertir su proyecto:

• instalación Pyment

Escriba el siguiente (se puede utilizar un virtualenv):

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

• convertido del Epydoc a Sphinx

Puede convertir su proyecto en formato Sphinx (reposo), que es el formato de salida predeterminado, haciendo:

$ pyment /my/folder/project