how - python documentation generator

¿Hay alguna alternativa real a reStructuredText para la documentación de Python?

Question

Estoy empezando un proyecto de Python de código abierto en breve y estoy tratando de decidir de antemano cómo escribir mis documentos. La respuesta obvia sería usar reStructuredText y Sphinx con autodoc, porque realmente me gusta la idea de simplemente documentar correctamente mi código en mis documentos y luego hacer que Sphinx construya automáticamente un documento API para mí.

El problema es la sintaxis reStructuredText que utiliza, creo que es completamente ilegible antes de que se represente. Por ejemplo:

: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

Realmente tienes que reducir la velocidad y tomarte un minuto para sacarle sentido a esa confusión sintáctica. Me gusta mucho más el modo Google ( Guía de estilo de Google Python ), cuya contraparte de lo anterior se ve así:

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

¡Más agradable! Pero, por supuesto, Sphinx no tendrá nada de eso y renderizará todo el texto después de "Args:" en una larga línea.

Entonces, para resumir, antes de ir y profanar mi base de código con esta sintaxis reStructuredText, me gustaría saber si hay alguna alternativa real para usarla y Sphinx, solo escribir mi propio documento API. Por ejemplo, ¿hay una extensión para Sphinx que maneja el estilo de docstring de Google Style Guide?

Answer 1

Creé una extensión de Sphinx que analiza cadenas de estilo de estilo de Google y NumPy, y las convierte a reStructuredText estándar.

Para usarlo, simplemente instálalo:

$ pip install sphinxcontrib-napoleon 

Y habilítalos en conf.py:

# conf.py

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

Más documentación sobre Napoleón aquí .

Answer 2

En realidad, reStructuredText así como la guía de estilo de PEP8 aplican principalmente para codificar la biblioteca estándar de Python, aunque muchos programadores de terceros también se ajustan a eso.

Estoy de acuerdo con usted en que el estilo de argumentos de Google es mucho mejor desde una perspectiva dentro del código. Pero también debería poder generar esa docstring con sphinx , con las nuevas líneas y sangría preservadas . Sin embargo, no sale tan bien como con un formato más esfinge .

De todos modos, no tienes que usar Sphinx, y dicho sea de paso, el módulo autodoc de sphinx es definitivamente solo una pequeña parte de él. Puede utilizar prácticamente cualquier generador de documentación que sea capaz de recuperar el contenido de cadenas de documentos, como epydoc (que admite epytext así como reStructuredText, Javadoc o Plaintext ) o pydoctor , o incluso uno más universal como Doxygen .

Pero definitivamente, la esfinge es bastante pitonica , muy conveniente de usar con Python, y hace que tu código sea consistente con el ecosistema de Python. Creo que no eres el único que piensa que esto es una "falta". Tal vez tomarán en cuenta estas quejas en el futuro, o tal vez incluso consideren la posibilidad de modificar el módulo autodoc por sí mismos, no debería ser muy difícil, es en Python, sería un buen ejercicio.

Answer 3

Puede escribir documentos en cualquier formato que desee. Sin embargo, por el bien de cualquier otro programador de Python, lo mejor es utilizar el marcado y las herramientas que ya conocen. Sus vidas son más fáciles si te apegas a reST y Sphinx.

Answer 4

Python hace que los contenidos de las cadenas de documentos estén disponibles como un atributo __doc__ adjunto al objeto función / clase / variable.

Por lo tanto, podría escribir trivialmente un programa de Python que convierta la documentación del formato que desee en el formato que desee. Incluso podría usar el estilo Javadoc, o XML, o lo que sea.

A propósito, dado que Sphinx está escrito en Python, hacer que tome entradas que no sean RST es solo cuestión de escribir una pequeña cantidad de código Python.

Answer 5

Yo uso epydoc y no sphinx, por lo que esta respuesta puede no aplicarse.

La sintaxis reStructuredText que describe para documentar métodos y funciones no es la única posible. De lejos, prefiero describir los parámetros usando una lista de definición consolidada , que es muy similar a la forma de 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

Yo probaría si sphix lo admite. Si no lo hace, también puede considerar usar epydoc solo para eso (aunque no es lo que se mantiene activamente en este momento).

Answer 6

solo necesita comenzar una nueva línea y agregar un toque después de cada nombre de variable. Luego se representa en varias líneas con nombres de variable audaces conspicuos:

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

No creo que haya algo mejor que sphinx para documentar proyectos Python en este momento.

Para tener un docstring más claro, mi elección favorita es usar sphinx junto con numpydoc . Según su ejemplo, esto se vería así:

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 ejemplo completo está Here ), el resultado HTML se verá así

Creo que la estructura del primer archivo es más clara y legible. La guide brinda más información y convenciones. La extensión numpydoc funciona con autodoc .