Parse Sphinx como documentación

Tengo una cadena de documentos con formato Sphinx de la que me gustaría extraer las diferentes partes (param, return, type, rtype, etc.) para su posterior procesamiento. ¿Cómo puedo conseguir esto?

preguntado el 03 de julio de 12 a las 01:07

Estas dos respuestas deberían ayudarlo a comenzar: stackoverflow.com/a/11117575/623518 y stackoverflow.com/a/10782270/623518 -

1 Respuestas

Podrías usar documentos, que es sobre lo que se basa Sphinx. En esta otra respuesta yo suelo docutils.core.publish_doctree para obtener una representación XML de un documento reStructuredText (en realidad, una cadena de texto) y luego extraer listas de campos de ese XML usando los métodos xml.minidom. Un método alternativo es usar xml.etree.ElementTree, que en mi opinión es mucho más fácil de usar.

Primero, sin embargo, cada vez que docutils encuentra un bloque de texto reStructured como

:param x: Some parameter

la representación XML resultante es (lo sé, es bastante detallado):

<field_list>
    <field>
        <field_name>
            param x
        </field_name>
        <field_body>
            <paragraph>
                Some parameter
            </paragraph>
        </field_body>
    </field>
</field_list>

El siguiente código tomará todos field_list elementos en un documento y poner el texto de field/field_name y field/field_body/paragraph como una tupla de 2 en una lista. Luego puede manipular esto como desee para el procesamiento posterior.

from docutils.core import publish_doctree
import xml.etree.ElementTree as etree

source = """Some help text

:param x: some parameter
:type x: and it's type

:return: Some text
:rtype: Return type

Some trailing text. I have no idea if the above is valid Sphinx
documentation!
"""

doctree = publish_doctree(source).asdom()

# Convert to etree.ElementTree since this is easier to work with than
# xml.minidom
doctree = etree.fromstring(doctree.toxml())

# Get all field lists in the document.
field_lists = doctree.findall('field_list')

fields = [f for field_list in field_lists \
    for f in field_list.findall('field')]

field_names = [name.text for field in fields \
    for name in field.findall('field_name')]

field_text = [etree.tostring(element) for field in fields \
    for element in field.findall('field_body')]

print zip(field_names, field_text)

Esto produce la lista:

[('param x', '<field_body><paragraph>some parameter</paragraph></field_body>'),
 ('type x', "<field_body><paragraph>and it's type</paragraph></field_body>"), 
 ('return', '<field_body><paragraph>Some text</paragraph></field_body>'), 
 ('rtype', '<field_body><paragraph>Return type</paragraph></field_body>')]

Entonces, el primer elemento de cada tupla es el elemento de la lista de campos (es decir, :return:, :param x: etc) y el segundo elemento es el texto correspondiente. Obviamente, este texto no es el resultado más limpio, pero el código anterior es bastante fácil de modificar, así que lo dejo en manos del OP para obtener el resultado exacto que desean.

contestado el 23 de mayo de 17 a las 13:05

Unknown directive type "highlight" - Boris

No es la respuesta que estás buscando? Examinar otras preguntas etiquetadas or haz tu propia pregunta.