Guía de estilo de la documentación #

Esta guía contiene las mejores prácticas para el lenguaje y el formato de la documentación de Matplotlib.

Ver también

Para obtener más información sobre cómo contribuir, consulte la sección Escribir documentación .

Lenguaje expositivo #

Para la escritura explicativa, las siguientes pautas son para un uso de lenguaje claro y conciso.

Terminología #

Hay varios términos clave en Matplotlib que son estándares de confiabilidad y consistencia en la documentación. No son intercambiables.

Término	Descripción	Correcto	Incorrecto
`Figure`	Espacio de trabajo Matplotlib para programación.	Para objetos de Matplotlib : Figura, "La figura es el espacio de trabajo para lo visual. Refiriéndose a la clase : `Figure`, "Métodos dentro de `Figure` proporcionar las imágenes". Lenguaje general : figura, "Michelle Kwan es una famosa patinadora artística".	"La figura es el espacio de trabajo para las imágenes". "Los métodos en la figura proporcionan las imágenes". "La `Figure` llave de cuatro piernas es un movimiento de lucha".
`Axes`	Subparcelas dentro de la figura. Contiene elementos de trama y es responsable de trazar y configurar detalles adicionales.	Para objetos de Matplotlib : ejes, "Un eje es una subtrama dentro de la figura". Refiriéndose a la clase : `Axes`"Cada uno `Axes`es específico de una figura". Lenguaje general : hachas, "Tanto los madereros como los leñadores usan hachas para cortar madera". O "No hay nombres estándar para las coordenadas en los tres ejes". (Plural de eje)	"Los métodos de los ejes transforman los datos". "Cada uno `Axes`es específico de una figura". "Los músicos en el escenario llaman a sus guitarras Axes". "El punto donde se encuentran los ejes es el origen del sistema de coordenadas".
`Artist`	Amplia variedad de objetos de Matplotlib que muestran imágenes.	Para objetos de Matplotlib : Artista, "Los artistas muestran elementos visuales y son los elementos visibles al representar una figura". Refiriéndose a la clase : `Artist`"Cada uno `Artist` tiene sus respectivos métodos y funciones". Lenguaje general : artista, "El artista en el museo es de Francia".	"Configurar el artista de la leyenda con su respectivo método". "Hay un `Artist` para ese visual en el gráfico". "Algunos artistas se hicieron famosos solo por accidente".
`Axis`	Objeto unidimensional legible por humanos de marcas de referencia que contienen marcas, etiquetas de marcas, espinas y bordes.	Para objetos Matplotlib : Axis, "El eje para el gráfico de barras es un artista separado". (plural, objetos Axis) En referencia a la clase : `Axis`" `Axis` Contiene los respectivos objetos XAxis y YAxis". Lenguaje general : eje, "La rotación alrededor de un eje fijo es un caso especial de movimiento de rotación".	"Dibuje el gráfico en el eje". "Cada eje generalmente recibe el nombre de la coordenada que se mide a lo largo de él". "En algunos contextos de gráficos por computadora, la ordenada `Axis`puede estar orientada hacia abajo".
Programación Explícita Orientada a Objetos (POO)	Enfoque explícito de programación en Matplotlib.	Explícito explícito Programación orientada a objetos	orientado a objetos estilo OO
Implícito, `pyplot`	Enfoque implícito de programación en Matplotlib con `pyplot`módulo.	Implícito implícito `pyplot`	MATLAB como Pyplot interfaz pyplot

Gramática #

Asunto #

Use oraciones imperativas en segunda persona para instrucciones dirigidas que especifican una acción. Los pronombres en segunda persona son para contextos individuales específicos y referencias posesivas.

Correcto	Incorrecto
Instale Matplotlib desde el directorio de origen utilizando el `pip` programa de instalación de Python. Dependiendo de su sistema operativo, es posible que necesite soporte adicional.	Puede instalar Matplotlib desde el directorio de origen. Puede encontrar soporte adicional si tiene problemas con su instalación.

Tiempo #

Usa el tiempo presente simple para las explicaciones. Evite el tiempo futuro y otros verbos modales o auxiliares cuando sea posible.

Correcto	Incorrecto
Las ideas fundamentales detrás de Matplotlib para la visualización implican tomar datos y transformarlos a través de funciones y métodos.	Matplotlib tomará datos y los transformará a través de funciones y métodos. Pueden generar muchos tipos de imágenes. Estos serán los fundamentos para usar Matplotlib.

Voz #

Escribe en oraciones activas. La voz pasiva es mejor para situaciones o condiciones relacionadas con avisos de advertencia.

Correcto	Incorrecto
La función `plot`genera el gráfico.	El gráfico es generado por la `plot`función.
La función devuelve un mensaje de error si no hay argumentos.	Verá un mensaje de error de la función si no hay argumentos.

Estructura de la oración #

Escribe con oraciones cortas usando el orden Sujeto-Verbo-Objeto regularmente. Limite las conjunciones coordinantes en oraciones. Evite referencias de pronombres y frases conjuntivas subordinantes.

Correcto	Incorrecto
El `pyplot`módulo en Matplotlib es una colección de funciones. Estas funciones crean, administran y manipulan la figura actual y el área de trazado.	El `pyplot`módulo en Matplotlib es una colección de funciones que crean, administran y manipulan la figura actual y el área de trazado.
La `plot`función traza datos en los ejes respectivos. Los Ejes corresponden a la Figura respectiva.	La `plot`función traza datos dentro de sus ejes respectivos para su figura respectiva.
El enfoque implícito es un atajo conveniente para generar diagramas simples.	Los usuarios que deseen tener accesos directos convenientes para generar gráficos utilizan el enfoque implícito.

Formateo #

Las siguientes pautas especifican cómo incorporar código y usar el formato adecuado para la documentación de Matplotlib.

Código #

Matplotlib es una biblioteca de Python y sigue los mismos estándares para la documentación.

Comentarios #

Los ejemplos de código Python tienen comentarios antes o en la misma línea.

Correcto	Incorrecto
# Data years = [2006, 2007, 2008]	years = [2006, 2007, 2008] # Data
years = [2006, 2007, 2008] # Data	years = [2006, 2007, 2008] # Data

Salidas #

Al generar elementos visuales con Matplotlib usando .pyarchivos en ejemplos, muestre el elemento visual con matplotlib.pyplot.showpara mostrar el elemento visual. Mantenga la documentación libre de líneas de salida de Python.

Correcto	Incorrecto
plt.plot([1, 2, 3], [1, 2, 3]) plt.show()	plt.plot([1, 2, 3], [1, 2, 3])
fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3]) fig.show()	fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3])

texto reestructurado #

Matplotlib usa reStructuredText Markup para la documentación. Sphinx ayuda a transformar estos documentos en formatos apropiados para accesibilidad y visibilidad.

Listas #

Las listas con viñetas son para elementos que no requieren secuenciación. Las listas numeradas son exclusivamente para realizar acciones en un orden determinado.

Correcto	Incorrecto
El ejemplo utiliza tres gráficos.	El ejemplo utiliza tres gráficos.
Bar Línea Tarta	Bar Línea Tarta
Estos cuatro pasos ayudan a comenzar a usar Matplotlib.	Los siguientes pasos son importantes para comenzar a usar Matplotlib.
Importe la biblioteca Matplotlib. Importe los módulos necesarios. Establecer y asignar datos para trabajar. Transforma datos con métodos y funciones.	Importe la biblioteca Matplotlib. Importe los módulos necesarios. Establecer y asignar datos para trabajar. Transforma datos con métodos y funciones.

Mesas #

Use tablas ASCII con estándares reStructuredText para organizar el contenido. No se aceptan las tablas Markdown ni la directiva csv-table.

Correcto

Incorrecto

Correcto	Incorrecto
OK	No está bien

| Correct | Incorrect |
| ------- | --------- |
| OK      | Not OK    |

+----------+----------+
| Correct  | Incorrect|
+==========+==========+
| OK       | Not OK   |
+----------+----------+

.. csv-table::
   :header: "correct", "incorrect"
   :widths: 10, 10

   "OK   ", "Not OK"

===========  ===========
  Correct     Incorrect
===========  ===========
OK           Not OK
===========  ===========

Recursos adicionales #

Esta guía de estilo no es un estándar completo. Para obtener una referencia más detallada sobre cómo contribuir a la documentación, consulte los enlaces a continuación. Estos recursos contienen mejores prácticas comunes para escribir documentación.