MEP10: consistencia de la cadena de documentos #

Estado #

Progreso

Esto sigue siendo un esfuerzo en curso

Sucursales y solicitudes de extracción #

Resumen #

matplotlib tiene una gran cantidad de inconsistencias entre cadenas de documentación. Esto no solo hace que los documentos sean más difíciles de leer, sino que también es más difícil para los colaboradores, porque no saben qué especificaciones seguir. Debe haber una convención de cadena de documentación clara que se siga de manera consistente.

La organización de la documentación de la API es difícil de seguir. Algunas páginas, como pyplot y axes, son enormes y difíciles de navegar. En su lugar, debería haber tablas breves de resumen que se vinculen a la documentación detallada. Además, algunas de las cadenas de documentación son bastante largas y contienen información redundante.

La creación de la documentación lleva mucho tiempo y utiliza un make.py script en lugar de un Makefile.

Descripción detallada #

Hay varias herramientas y convenciones nuevas disponibles desde que matplotlib comenzó a usar Sphinx que hacen la vida más fácil. La siguiente es una lista de los cambios propuestos a las cadenas de documentos, la mayoría de los cuales involucran estas nuevas funciones.

Formato de cadena de documentación numpy #

Formato de cadena de documentación Numpy : este formato divide la cadena de documentación en secciones claras, cada una con diferentes reglas de análisis que hacen que la cadena de documentación sea fácil de leer tanto como texto sin formato como HTML. Podríamos considerar alternativas o inventar las nuestras, pero esta es una buena opción, ya que se usa y se entiende bien en la comunidad de Numpy/Scipy.

Referencias cruzadas #

La mayoría de las cadenas de documentos en matplotlib usan "roles" explícitos cuando se vinculan a otros elementos, por ejemplo: :func:`myfunction`. A partir de Sphinx 0.4, hay un "default_role" que se puede establecer en "obj", que se vinculará polimórficamente a un objeto de Python de cualquier tipo. Esto permite que uno escriba `myfunction`en su lugar. Esto hace que las cadenas de documentos sean mucho más fáciles de leer y editar como texto sin formato. Además, Sphinx permite configurar un módulo actual, por lo que los enlaces `~matplotlib.axes.Axes.set_xlim` podrían escribirse como `~axes.Axes.set_xlim`.

Anulación de firmas #

Muchos métodos en matplotlib usan la sintaxis *argsy **kwargspara manejar dinámicamente los argumentos de palabras clave que son aceptados por la función, o para delegar a otra función. Esto, sin embargo, a menudo no es útil como firma en la documentación. Por esta razón, muchos métodos de matplotlib incluyen algo como:

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

Esto no puede ser analizado por Sphinx, y es bastante detallado en texto sin formato. A partir de Sphinx 1.1, si el autodoc_docstring_signaturevalor de configuración se establece en True, Sphinx extraerá una firma de reemplazo de la primera línea de la cadena de documentación, lo que permitirá lo siguiente:

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

La firma explícita reemplazará a la de Python real en la documentación generada.

Vincular en lugar de duplicar #

Muchas de las cadenas de documentación incluyen largas listas de palabras clave aceptadas mediante la interpolación de cosas en la cadena de documentación en el momento de la carga. Esto hace que las cadenas de documentación sean muy largas. Además, dado que estas tablas son las mismas en muchas cadenas de documentos, inserta mucha información redundante en los documentos, particularmente un problema en la versión impresa.

Estas tablas deben moverse a cadenas de documentación sobre funciones cuyo único propósito es ayudar. Las cadenas de documentación que hacen referencia a estas tablas deben vincularse a ellas, en lugar de incluirlas palabra por palabra.

extensión de resumen automático #

La extensión de resumen automático Sphinx debe usarse para generar tablas de resumen, que se vinculan a páginas separadas de documentación. Algunas clases que tienen muchos métodos (por ejemplo Axes, ) deben documentarse con un método por página, mientras que las clases más pequeñas deben tener todos sus métodos juntos.

Ejemplos con enlaces a documentación relevante #

Los ejemplos, si bien son útiles para ilustrar cómo usar una función, no se vinculan a las cadenas de documentación relevantes. Esto podría solucionarse agregando cadenas de documentación a nivel de módulo a los ejemplos y luego incluyendo esa cadena de documentación en el contenido analizado en la página de ejemplo. Estas cadenas de documentación podrían incluir fácilmente referencias a cualquier otra parte de la documentación.

Documentación usando ayuda() vs. un navegador #

El uso del marcado Sphinx en la fuente permite que los documentos se vean atractivos en su navegador, pero el marcado también hace que el texto sin procesar que se devuelve usando help() se vea terrible. Uno de los objetivos de mejorar las cadenas de documentos debería ser hacer que ambos métodos de acceso a los documentos se vean bien.

Implementación #

  1. Las extensiones numpydoc deben estar activadas para matplotlib. Existe una pregunta importante sobre si estos deben incluirse en el árbol de fuentes de matplotlib o usarse como una dependencia. Instalar Numpy no es suficiente para obtener las extensiones numpydoc; es un procedimiento de instalación independiente. En cualquier caso, en la medida en que requieran personalización para nuestras necesidades, debemos esforzarnos por enviar esos cambios aguas arriba y no bifurcarlos.

  2. Revise manualmente todas las cadenas de documentación y actualícelas al nuevo formato y convenciones. La actualización de las referencias cruzadas (de `:func:`myfunc`a `func`) puede ser semiautomática. Esto es mucho trabajo ocupado, y tal vez este trabajo debería dividirse por módulo para que ningún desarrollador se vea sobrecargado.

  3. Reorganice los documentos de la API mediante autosummary y sphinx-autogen. Con suerte, esto debería tener un impacto mínimo en la documentación narrativa.

  4. Modifique el generador de páginas de ejemplo ( gen_rst.py) para que extraiga la cadena de documentación del módulo del ejemplo y la incluya en una parte no literal de la página de ejemplo.

  5. Úselo sphinx-quickstartpara generar un Sphinx Makefile de nuevo estilo. Las siguientes características en el actual make.pytendrán que ser abordadas de alguna otra manera:

    • Copia de algún contenido estático

    • Especificar una compilación "pequeña" (solo archivos PNG de baja resolución para ejemplos)

Los pasos 1, 2 y 3 son interdependientes. 4 y 5 se pueden hacer de forma independiente, aunque 5 depende en cierta medida de 3.

Compatibilidad con versiones anteriores #

Como esto involucra principalmente cadenas de documentos, debería haber un impacto mínimo en la compatibilidad con versiones anteriores.

Alternativas #

Ninguno discutido todavía.