MEP12: Mejorar Galería y Ejemplos #

Estado #

Progreso

Los cambios iniciales se agregaron en 1.3. La conversión de la galería está en curso. 29 de septiembre de 2015: el último pylab_examplesdonde pylabse importa se convirtió para usar matplotlib.pyploty numpy.

Sucursales y solicitudes de extracción #

#1623, #1924, #2181

PR #2474 muestra un solo ejemplo siendo limpiado y movido a la sección apropiada.

Resumen #

La reorganización de la galería de gráficos de matplotlib simplificaría en gran medida la navegación de la galería. Además, los ejemplos deben limpiarse y simplificarse para mayor claridad.

Descripción detallada #

La galería matplotlib se configuró recientemente para dividir los ejemplos en secciones. Como se discutió en ese PR [ 1 ] , las secciones de ejemplo actuales ( api, pylab_examples) no son muy útiles para los usuarios: las nuevas secciones en la galería ayudarían a los usuarios a encontrar ejemplos relevantes.

Estas secciones también guiarían una limpieza de los ejemplos: Inicialmente, todos los ejemplos actuales permanecerían y se enumerarían en sus directorios actuales. Con el tiempo, estos ejemplos podrían limpiarse y trasladarse a una de las nuevas secciones.

Este proceso permite a los usuarios identificar fácilmente los ejemplos que deben limpiarse; es decir, cualquier cosa en los directorios apiy pylab_examples .

Implementación #

Crear nuevas secciones de galería. [Hecho]
Limpie los ejemplos y muévalos a las nuevas secciones de la galería (en el transcurso de muchas relaciones públicas y con la ayuda de muchos usuarios/desarrolladores). [En progreso]

Secciones de la galería #

El nombre de las secciones es crítico y guiará el esfuerzo de limpieza. Las secciones actuales son:

Líneas, barras y marcadores (más o menos datos 1D)
formas y colecciones
Gráficos estadísticos
Imágenes, contornos y campos.
Gráficos circulares y polares: cosas redondas
Color
Texto, etiquetas y anotaciones
Garrapatas y espinas
Subparcelas, ejes y figuras
Parcelas especiales (p. ej., sankey, radar, tornado)
Showcase (parcelas con ajustes para que tengan calidad de publicación)
secciones separadas para cajas de herramientas (ya existe: 'mplot3d', 'axes_grid', 'units', 'widgets')

Estos nombres son ciertamente objeto de debate. A medida que crezcan estas secciones, debemos reevaluarlas y dividirlas según sea necesario.

Directrices de limpieza #

Los ejemplos actuales en las secciones apiy pylab_examplesde la galería permanecerían en esos directorios hasta que se limpien. Después de la limpieza, se trasladarían a una de las nuevas secciones de la galería descritas anteriormente. La "limpieza" debe implicar:

sphinx-gallery docstrings : un título y una descripción del ejemplo con el siguiente formato, en la parte superior del ejemplo:

"""
===============================
Colormaps alter your perception
===============================

Here I plot the function

.. math:: f(x, y) = \sin(x) + \cos(y)

with different colormaps. Look at how colormaps alter your perception!
"""

Limpiezas de PEP8 (se recomienda encarecidamente ejecutar flake8 o un verificador similar)
El código comentado debe eliminarse.
Reemplace los usos de pylabla interfaz con pyplot(+ numpy, etc.). Ver c25ef1e
Retire la línea shebang, por ejemplo:

#!/usr/bin/env python
Usa importaciones consistentes. En particular:

importar numpy como np

importar matplotlib.pyplot como plt

Evite importar funciones específicas de estos módulos (por ejemplo, )from numpy import sin
Cada ejemplo debe centrarse en una característica específica (excepto los showcaseejemplos, que mostrarán gráficos más "pulidos"). Los ajustes no relacionados con esa función deben eliminarse. Ver f7b2217 , e57b5fc y 1458aa8

El uso de pylabdebe ser demostrado/discutido en una página de ayuda dedicada en lugar de los ejemplos de la galería.

Nota: Al mover un ejemplo existente, debe buscar referencias a ese ejemplo. Por ejemplo, la documentación de la API para axes.pyy pyplot.pypuede usar estos ejemplos para generar gráficos. Utilice su herramienta de búsqueda favorita (p. ej., grep, ack, grin , pss ) para buscar el paquete matplotlib. Ver 2dc9a46 y aa6b410

Sugerencias adicionales #

Proporcione enlaces (en ambos sentidos) entre ejemplos y documentos API para los métodos/objetos utilizados. (número 2222 )
Utilice plt.subplots(observe la "s" final) con preferencia sobre plt.subplot.
Cambie el nombre del ejemplo para aclarar su propósito. Por ejemplo, la demostración más básica de imshowpodría ser imshow_demo.pyy una que demuestre diferentes configuraciones de interpolación sería imshow_demo_interpolation.py( no imshow_demo2.py ).
Divide los ejemplos que intentan hacer demasiado. Ver 5099675 y fc2ab07
Eliminar ejemplos que no muestran nada nuevo.
Algunos ejemplos ejercen características esotéricas para pruebas unitarias. Estos ajustes deben moverse fuera de la galería a un ejemplo en el unitdirectorio ubicado en el directorio raíz del paquete.
Agregue títulos de trama para aclarar la intención del ejemplo. Ver bd2b13c

Compatibilidad con versiones anteriores #

Se puede acceder fácilmente al sitio web de cada versión de Matplotlib, por lo que los usuarios que deseen consultar ejemplos antiguos aún pueden hacerlo.

Alternativas #

Etiquetas #

Etiquetar ejemplos también ayudará a los usuarios a buscar en la galería de ejemplos. Aunque las etiquetas serían una gran ventaja para los usuarios con objetivos específicos, la galería de gráficos seguirá siendo el punto de entrada a estos ejemplos, y las secciones realmente podrían ayudar a los usuarios a navegar por la galería. Por lo tanto, las etiquetas son complementarias a esta reorganización.