Escritura de documentación #

Empezando #

Estructura general de archivos #

Toda la documentación está construida a partir del doc/. El doc/ directorio contiene archivos de configuración para Sphinx y archivos reStructuredText ( ReST ; .rst) que se representan en páginas de documentación.

La documentación se crea de tres maneras. En primer lugar, Sphinx crea la documentación de la API ( doc/api) a partir de las cadenas de documentación de las clases en la biblioteca Matplotlib. A excepción de , los archivos se crean cuando se crea la documentación. Consulte Escribir cadenas de documentación a continuación.doc/api/api_changes/.rstdoc/api

En segundo lugar, los contenidos de doc/plot_types, doc/galleryy doc/tutorialsson generados por Sphinx Gallery a partir de archivos python en plot_types/, examples/y tutorials/. Estas fuentes consisten en secuencias de comandos de python que tienen documentación de ReST integrada en sus comentarios. Consulte Ejemplos de escritura y tutoriales a continuación.

En tercer lugar, Matplotlib tiene documentos narrativos escritos en ReST en subdirectorios de doc/users/. Si desea agregar nueva documentación que se adapte a un .rstarchivo en lugar de una galería o un ejemplo de tutorial, elija un subdirectorio apropiado para colocarlo y agregue el archivo a la tabla de contenido del index.rstsubdirectorio. Consulte Escribir las páginas de ReST a continuación.

Nota

No edite directamente los .rstarchivos en doc/plot_types, doc/gallery, doc/tutorialsy doc/api (excepto doc/api/api_changes/). Sphinx regenera archivos en estos directorios al crear la documentación.

Configurando la compilación del documento #

La documentación para Matplotlib se genera a partir de reStructuredText ( ReST ) utilizando la herramienta de generación de documentación Sphinx .

Para crear la documentación, deberá configurar Matplotlib para el desarrollo . Tenga en cuenta en particular las dependencias adicionales requeridas para construir la documentación.

Construyendo los documentos #

Las fuentes de documentación se encuentran en el doc/directorio del baúl. El archivo de configuración de Sphinx es doc/conf.py. Controla qué directorios analiza Sphinx, cómo se construyen los documentos y cómo se usan las extensiones. Para compilar la documentación en formato html, ingrese doc/y ejecute:

make html

Otras invocaciones útiles incluyen

# Delete built files.  May help if you get errors about missing paths or
# broken links.
make clean

# Build pdf docs.
make latexpdf

La SPHINXOPTSvariable está configurada de forma predeterminada para compilar los documentos completos, pero sale con el estado de salida 1 si hay advertencias. Para desactivarlo, utilice-W --keep-going

make SPHINXOPTS= html

Puede utilizar la Ovariable para establecer opciones adicionales:

  • make O=-j4 htmlejecuta una compilación paralela con 4 procesos.

  • make O=-Dplot_formats=png:100 htmlguarda las cifras en baja resolución.

  • make O=-Dplot_gallery=0 htmlsalta la construcción de la galería.

Se pueden combinar varias opciones, p .make O='-j4 -Dplot_gallery=0' html

En Windows, establezca las opciones como variables de entorno, por ejemplo:

set SPHINXOPTS= & set O=-j4 -Dplot_gallery=0 & make html

Mostrando documentos creados localmente #

Los documentos creados están disponibles en la carpeta build/html. Un atajo para abrirlos en su navegador predeterminado es:

make show

Escritura de páginas ReST #

La mayor parte de la documentación se encuentra en las cadenas de documentación de clases y métodos individuales, en .rstarchivos explícitos o en ejemplos y tutoriales. Todos estos usan la sintaxis ReST y son procesados ​​por Sphinx .

Sphinx reStructuredText Primer es una buena introducción al uso de ReST. Hay información más completa disponible en la documentación de referencia de reStructuredText .

Esta sección contiene información adicional y convenciones sobre cómo se usa ReST en la documentación de Matplotlib.

Convenciones de formato y estilo #

Es útil luchar por la coherencia en la documentación de Matplotlib. Estas son algunas convenciones de formato y estilo que se utilizan.

Formato de sección #

Para todo menos los capítulos de nivel superior, utilícelo para títulos de sección, por ejemplo, en lugar deUpper lowerPossible hangupsPossible Hangups

Nuestro objetivo es seguir las recomendaciones de la documentación de Python y la documentación de Sphinx reStructuredText para los caracteres de marcado de sección, es decir:

  • #con overline, para piezas. Esto está reservado para el título principal en index.rst. Todas las demás páginas deben comenzar con "capítulo" o inferior.

  • *con overline, para capítulos

  • =, para secciones

  • -, para subsecciones

  • ^, para subsubsecciones

  • ", para párrafos

Es posible que esto aún no se aplique de manera consistente en los documentos existentes.

Argumentos de función #

Se debe hacer referencia a los argumentos de función y las palabras clave dentro de las cadenas de documentación mediante el *emphasis*rol. Esto mantendrá la documentación de Matplotlib consistente con la documentación de Python:

Here is a description of *argument*

No utilice el :`default role`

Do not describe `argument` like this.  As per the next section,
this syntax will (unsuccessfully) attempt to resolve the argument as a
link to a class or method in the library.

ni el ``literal``papel:

Do not describe ``argument`` like this.

Referencia a otros documentos y secciones #

Sphinx permite referencias internas entre documentos.

Los documentos se pueden vincular con la :doc:directiva:

See the :doc:`/users/installing/index`

See the tutorial :doc:`/tutorials/introductory/quick_start`

See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`

se representará como:

Ver la instalación

Ver el tutorial Guía de inicio rápido

Ver el ejemplo Gráfico simple

Las secciones también pueden recibir nombres de referencia. Por ejemplo, desde el enlace de instalación :

.. _clean-install:

How to completely remove Matplotlib
===================================

Occasionally, problems with Matplotlib can be solved with a clean...

y refiérase a él usando la sintaxis de referencia estándar:

See :ref:`clean-install`

dará el siguiente enlace: Cómo eliminar completamente Matplotlib

Para maximizar la coherencia interna en el etiquetado y las referencias de las secciones, utilice etiquetas descriptivas separadas por guiones para las referencias de las secciones. Tenga en cuenta que los contenidos pueden reorganizarse más adelante, así que evite los nombres de nivel superior en las referencias como usero devel o faqa menos que sea necesario, porque, por ejemplo, la pregunta frecuente "¿qué es un backend?" más tarde podría convertirse en parte de la guía del usuario, por lo que la etiqueta:

.. _what-is-a-backend:

es mejor que:

.. _faq-backend:

Además, dado que el propio Sphinx utiliza mucho los guiones bajos, utilice guiones para separar las palabras.

Refiriéndose a otro código #

Para vincular a otros métodos, clases o módulos en Matplotlib, puede usar marcas de retroceso, por ejemplo:

`matplotlib.collections.LineCollection`

genera un enlace como este: matplotlib.collections.LineCollection.

Nota: Usamos la configuración de esfinge para que no tenga que usar calificadores como , y similares .default_role = 'obj':class::func::meth:

A menudo, no desea mostrar el paquete completo y el nombre del módulo. Siempre que el objetivo no sea ambiguo, simplemente puede omitirlo:

`.LineCollection`

y el enlace sigue funcionando: LineCollection.

Si hay varios elementos de código con el mismo nombre (por ejemplo, plot()es un método en varias clases), deberá ampliar la definición:

`.pyplot.plot` or `.Axes.plot`

Estos aparecerán como pyplot.ploto Axes.plot. Para mostrar solo el último segmento, puede agregar una tilde como prefijo:

`~.pyplot.plot` or `~.Axes.plot`

se representará como ploto plot.

Otros paquetes también se pueden vincular a través de intersphinx :

`numpy.mean`

devolverá este enlace: numpy.mean. Esto funciona para Python, Numpy, Scipy y Pandas (la lista completa está en doc/conf.py). Si falla la vinculación externa, puede consultar la lista completa de objetos referenciables con los siguientes comandos:

python -m sphinx.ext.intersphinx 'https://docs.python.org/3/objects.inv'
python -m sphinx.ext.intersphinx 'https://numpy.org/doc/stable/objects.inv'
python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/scipy/objects.inv'
python -m sphinx.ext.intersphinx 'https://pandas.pydata.org/pandas-docs/stable/objects.inv'

Incluyendo figuras y archivos #

Los archivos de imagen pueden incluirse directamente en las páginas con la image::directiva. por ejemplo, tutorials/intermediate/constrainedlayout_guide.pymuestra un par de imágenes estáticas:

# .. image:: /_static/constrained_layout_1b.png
#    :align: center

Los archivos se pueden incluir palabra por palabra. Por ejemplo, el LICENSEarchivo se incluye en el acuerdo de licencia utilizando

.. literalinclude:: ../../LICENSE/LICENSE

sphinx-gallery copia doc/galleryel directorio de ejemplos, por lo que se pueden incluir gráficos del directorio de ejemplos usando

.. plot:: gallery/lines_bars_and_markers/simple_plot.py

Tenga en cuenta que se hace referencia a la secuencia de comandos de Python que genera la trama, en lugar de a cualquier trama que se cree. Sphinx-gallery proporcionará la referencia correcta cuando se construya la documentación.

Escribiendo cadenas de documentación #

La mayor parte de la documentación de la API está escrita en docstrings. Estos son bloques de comentarios en el código fuente que explican cómo funciona el código.

Nota

Algunas partes de la documentación aún no se ajustan al estilo de documentación actual. En caso de duda, siga las reglas dadas aquí y no lo que puede ver en el código fuente. Las solicitudes de extracción que actualizan las cadenas de documentos al estilo actual son muy bienvenidas.

Todas las cadenas de documentación nuevas o editadas deben ajustarse a la guía de cadenas de documentación numpydoc . Gran parte de la sintaxis de ReST discutida anteriormente ( Escribir páginas de ReST ) se puede usar para enlaces y referencias. Estos docstrings eventualmente llenan el doc/apidirectorio y forman la documentación de referencia para la biblioteca.

Ejemplo de cadena de documentación #

Una cadena de documentación de ejemplo se ve así:

def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',
           label='', **kwargs):
    """
    Plot horizontal lines at each *y* from *xmin* to *xmax*.

    Parameters
    ----------
    y : float or array-like
        y-indexes where to plot the lines.

    xmin, xmax : float or array-like
        Respective beginning and end of each line. If scalars are
        provided, all lines will have the same length.

    colors : list of colors, default: :rc:`lines.color`

    linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional

    label : str, default: ''

    Returns
    -------
    `~matplotlib.collections.LineCollection`

    Other Parameters
    ----------------
    data : indexable object, optional
        DATA_PARAMETER_PLACEHOLDER
    **kwargs :  `~matplotlib.collections.LineCollection` properties.

    See Also
    --------
    vlines : vertical lines
    axhline : horizontal line across the Axes
    """

Consulte la hlinesdocumentación para saber cómo se representa esto.

El sitio web de Sphinx también contiene mucha documentación sobre el marcado ReST y el trabajo con Sphinx en general.

Convenciones de formato #

Las convenciones básicas de cadenas de documentación se tratan en la guía de cadenas de documentación numpydoc y en la documentación de Sphinx . Algunas convenciones de formato específicas de Matplotlib a tener en cuenta:

Cotizar posiciones #

Las comillas para cadenas de documentos de una sola línea están en la misma línea (pydocstyle D200):

def get_linewidth(self):
    """Return the line width in points."""

Las comillas para cadenas de documentos de varias líneas están en líneas separadas (pydocstyle D213):

def set_linestyle(self, ls):
"""
Set the linestyle of the line.

[...]
"""

Argumentos de función #

Se debe hacer referencia a los argumentos de función y las palabras clave dentro de las cadenas de documentación mediante el *emphasis*rol. Esto mantendrá la documentación de Matplotlib consistente con la documentación de Python:

If *linestyles* is *None*, the default is 'solid'.

No use el o el rol:`default role```literal``

Neither `argument` nor ``argument`` should be used.

Cotizaciones para cadenas #

Matplotlib no tiene una convención sobre el uso de comillas simples o dobles. Hay una mezcla de ambos en el código actual.

Use comillas simples o dobles simples al dar valores de cadena, por ejemplo

If 'tight', try to figure out the tight bbox of the figure.

No ``'extra'`` literal quotes.

Se desaconseja el uso de comillas extra literales alrededor del texto. Si bien mejoran ligeramente los documentos renderizados, son engorrosos de escribir y difíciles de leer en documentos de texto sin formato.

Descripciones de tipo de parámetro #

El objetivo principal de las descripciones de tipos de parámetros es que sean legibles y comprensibles para los humanos. Si los tipos posibles son demasiado complejos, use una simplificación para la descripción del tipo y explique el tipo con mayor precisión en el texto.

En general, se aplican las convenciones de la guía de cadenas de documentos numpydoc . Las siguientes reglas las amplían donde las convenciones numpydoc no son específicas.

Úselo floatpara un tipo que puede ser cualquier número.

Úselo para describir una posición 2D. Los paréntesis deben incluirse para que la tupla sea más obvia.(float, float)

Úselo array-likepara secuencias numéricas homogéneas, que normalmente podrían ser una matriz numpy. La dimensionalidad se puede especificar mediante 2D, 3D, n-dimensional. Si necesita tener variables que indiquen los tamaños de las dimensiones, use letras mayúsculas entre paréntesis ( ). Cuando se hace referencia a ellos en el texto, son más fáciles de leer y no se necesita un formato especial. Úselo en lugar de para tipos de devolución si el objeto devuelto es de hecho una matriz numpy.(M, N) array-likearrayarray-like

floates el dtype predeterminado implícito para los me gusta de matriz. Para otros tipos de d, use .array-like of int

Algunos usos posibles:

2D array-like
(N,) array-like
(M, N) array-like
(M, N, 3) array-like
array-like of int

Las secuencias homogéneas no numéricas se describen como listas, por ejemplo:

list of str
list of `.Artist`

Tipos de referencia #

En general, se aplican las reglas de referencia a otro código . Más específicamente:

Utilice referencias completas `~matplotlib.colors.Normalize`con una tilde de abreviatura en los tipos de parámetros. Si bien el nombre completo ayuda al lector de cadenas de documentos de texto sin formato, el HTML no necesita mostrar el nombre completo ya que se vincula a él. Por lo tanto, el ~acortamiento lo hace más legible.

Utilice enlaces abreviados `.Normalize`en el texto.

norm : `~matplotlib.colors.Normalize`, optional
     A `.Normalize` instance is used to scale luminance data to 0, 1.

Valores predeterminados #

A diferencia de la guía numpydoc, no es necesario marcar los parámetros como opcionales si tienen un valor predeterminado simple:

  • utilizar cuando sea posible.{name} : {type}, default: {val}

  • use y describa el valor predeterminado en el texto si no se puede explicar suficientemente de la manera recomendada.{name} : {type}, optional

El valor predeterminado debe proporcionar información semántica dirigida a un lector humano. En casos simples, reafirma el valor en la firma de la función. Si corresponde, se deben agregar unidades.

Prefer:
    interval : int, default: 1000ms
over:
    interval : int, default: 1000

Si Ninguno solo se usa como valor centinela para "parámetro no especificado", no lo documente como valor predeterminado. Dependiendo del contexto, proporcione el valor predeterminado real o marque el parámetro como opcional si no especificar no tiene ningún efecto particular.

Prefer:
    dpi : float, default: :rc:`figure.dpi`
over:
    dpi : float, default: None

Prefer:
    textprops : dict, optional
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.
over:
    textprops : dict, default: None
        Dictionary of keyword parameters to be passed to the
        `~matplotlib.text.Text` instance contained inside TextArea.

See alsosecciones #

Sphinx vincula automáticamente elementos de código en los bloques de definición de las secciones. No es necesario usar acentos graves allí:See also

See Also
--------
vlines : vertical lines
axhline : horizontal line across the Axes

Envolviendo listas de parámetros #

Las listas de parámetros largos deben ajustarse usando una \continuación de for y comenzando en la nueva línea sin ninguna sangría (sin sangría porque pydoc analizará la cadena de documentación y eliminará la continuación de la línea para que la sangría resulte en una gran cantidad de espacios en blanco dentro de la línea):

def add_axes(self, *args, **kwargs):
    """
    ...

    Parameters
    ----------
    projection : {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
'rectilinear'}, optional
        The projection type of the axes.

    ...
    """

Como alternativa, puede describir los valores de parámetros válidos en una sección dedicada de la cadena de documentación.

rcParams #

Se puede hacer referencia a rcParams con el :rc:rol personalizado: :rc:`foo`yields , que es un enlace a la descripción del archivo.rcParams["foo"] = 'default'matplotlibrc

Setters y getters #

Las propiedades del artista se implementan utilizando métodos setter y getter (porque Matplotlib es anterior al propertydecorador de Python). Por convención, estos setters y getters se nombran set_PROPERTYNAMEy get_PROPERTYNAME; la lista de propiedades así definidas en un artista y sus valores pueden listarse mediante las funciones setpy getp.

El bloque de parámetros de los métodos de establecimiento de propiedades se analiza para documentar los valores aceptados, por ejemplo, la cadena de documentación de Line2D.set_linestylecomienza con

def set_linestyle(self, ls):
    """
    Set the linestyle of the line.

    Parameters
    ----------
    ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
        etc.
    """

lo que da como resultado la siguiente línea en la salida de plt.setp(line)o :plt.setp(line, "linestyle")

linestyle or ls: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

En algunos casos raros (principalmente, setters que aceptan tanto una tupla única como una tupla desempaquetada), los valores aceptados no pueden documentarse de esa manera; en ese caso, se pueden documentar como un bloque, por ejemplo, para :.. ACCEPTS:axes.Axes.set_xlim

def set_xlim(self, ...):
    """
    Set the x-axis view limits.

    Parameters
    ----------
    left : float, optional
        The left xlim in data coordinates. Passing *None* leaves the
        limit unchanged.

        The left and right xlims may also be passed as the tuple
        (*left*, *right*) as the first positional argument (or as
        the *left* keyword argument).

        .. ACCEPTS: (bottom: float, top: float)

    right : float, optional
        etc.
    """

Tenga en cuenta que el encabezado ..hace que el bloque sea un comentario reST, ocultándolo de los documentos renderizados... ACCEPTS:

Argumentos de palabra clave #

Nota

El equipo de desarrollo está discutiendo activamente la información en esta sección, así que use la interpolación de cadenas de documentación solo si es necesario. Esta sección se ha dejado en su lugar por ahora porque esta interpolación es parte de la documentación existente.

Dado que Matplotlib usa mucho pass-through kwargs, por ejemplo, en cada función que crea una línea ( plot, semilogx, semilogy, etc.), puede ser difícil para el nuevo usuario saber cuáles kwargsson compatibles. Matplotlib usa un esquema de interpolación de cadenas de documentos para respaldar la documentación de cada función que toma un archivo **kwargs. Los requisitos son:

  1. punto único de configuración para que los cambios en las propiedades no requieran múltiples ediciones de cadenas de documentación.

  2. lo más automatizado posible para que, a medida que cambien las propiedades, los documentos se actualicen automáticamente.

El @_docstring.interpddecorador implementa esto. Cualquier función que acepte Line2Dpass-through kwargs, por ejemplo, matplotlib.axes.Axes.plotpuede listar un resumen de las Line2Dpropiedades, como sigue:

# in axes.py
@_docstring.interpd
def plot(self, *args, **kwargs):
    """
    Some stuff omitted

    Other Parameters
    ----------------
    scalex, scaley : bool, default: True
        These parameters determine if the view limits are adapted to the
        data limits. The values are passed on to `autoscale_view`.

    **kwargs : `.Line2D` properties, optional
        *kwargs* are used to specify properties like a line label (for
        auto legends), linewidth, antialiasing, marker face color.
        Example::

        >>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2)
        >>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2')

        If you specify multiple lines with one plot call, the kwargs apply
        to all those lines. In case the label object is iterable, each
        element is used as labels for each set of data.

        Here is a list of available `.Line2D` properties:

        %(Line2D:kwdoc)s
    """

La %(Line2D:kwdoc)sintaxis hace que interpdbusque una Artistsubclase llamada Line2Dy llame artist.kwdoca esa clase. artist.kwdoc introspecciona la subclase y resume sus propiedades como una subcadena, que se interpola en la cadena de documentación.

Tenga en cuenta que este esquema no funciona para decorar un Artist's __init__, ya que la subclase y sus propiedades aún no están definidas en ese momento. En cambio, @_docstring.interpdse puede usar para decorar la clase en sí; en ese punto, kwdocse pueden enumerar las propiedades e interpolarlas en __init__.__doc__.

Heredar cadenas de documentación #

Si una subclase anula un método pero no cambia la semántica, podemos reutilizar la cadena de documentación principal para el método de la clase secundaria. Python hace esto automáticamente, si el método de la subclase no tiene una cadena de documentación.

Use un comentario simple para indicar la intención de reutilizar la cadena de documentación principal. De esa manera, no creamos accidentalmente una cadena de documentación en el futuro:# docstring inherited

class A:
    def foo():
        """The parent docstring."""
        pass

class B(A):
    def foo():
        # docstring inherited
        pass

Adición de cifras #

Como se indicó anteriormente (consulte Incluir figuras y archivos ), se puede hacer referencia a las figuras en la galería de ejemplos con una directiva que apunte a la secuencia de comandos de Python que creó la figura. Por ejemplo, la cadena de documentación hace referencia al archivo :.. plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

.. plot:: gallery/text_labels_and_annotations/legend.py
"""

Tenga en cuenta que examples/text_labels_and_annotations/legend.pyse ha asignado a gallery/text_labels_and_annotations/legend.py, una redirección que puede corregirse en una futura reorganización de los documentos.

Los gráficos también se pueden colocar directamente dentro de cadenas de documentos. Los detalles están en matplotlib.sphinxext.plot_directive . Un breve ejemplo es:

"""
...

Examples
--------

.. plot::
   import matplotlib.image as mpimg
   img = mpimg.imread('_static/stinkbug.png')
   imgplot = plt.imshow(img)
"""

Una ventaja de este estilo sobre la referencia a un script de ejemplo es que el código también aparecerá en cadenas de documentación interactivas.

Ejemplos de escritura y tutoriales #

Los ejemplos y tutoriales son secuencias de comandos de Python que Sphinx Gallery ejecuta para crear una galería de imágenes en los directorios /doc/galleryy /doc/tutorialsrespectivamente. Para excluir un ejemplo de tener un gráfico generado, inserte "sgskip" en algún lugar del nombre del archivo.

El formato de estos archivos es relativamente sencillo. Los bloques de comentarios con el formato adecuado se tratan como texto ReST , se muestra el código y las cifras se colocan en la página creada.

Por ejemplo, el ejemplo de gráfico simple se genera a partir de /examples/lines_bars_and_markers/simple_plot.py, que se ve así:

"""
===========
Simple Plot
===========

Create a simple plot.
"""
import matplotlib.pyplot as plt
import numpy as np

# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)

# Note that using plt.subplots below is equivalent to using
# fig = plt.figure and then ax = fig.add_subplot(111)
fig, ax = plt.subplots()
ax.plot(t, s)

ax.set(xlabel='time (s)', ylabel='voltage (mV)',
       title='About as simple as it gets, folks')
ax.grid()
plt.show()

El primer bloque de comentarios se trata como texto ReST . Los otros bloques de comentarios se representan como comentarios en Simple Plot .

Los tutoriales se crean exactamente con el mismo mecanismo, excepto que son más largos y, por lo general, tienen más de un bloque de comentarios (es decir, una guía de inicio rápido ). El primer bloque de comentarios puede ser el mismo que el ejemplo anterior. Los bloques posteriores de texto ReST están delimitados por una línea de ###caracteres:

"""
===========
Simple Plot
===========

Create a simple plot.
"""
...
ax.grid()
plt.show()

##########################################################################
# Second plot
# ===========
#
# This is a second plot that is very nice

fig, ax = plt.subplots()
ax.plot(np.sin(range(50)))

De esta forma, el texto, el código y las figuras se imprimen en un estilo de "cuaderno de notas".

Varios #

Documentación de mudanza #

A veces es conveniente mover o consolidar la documentación. Si no se realiza ninguna acción, los enlaces dejarán de funcionar (404) o apuntarán a versiones anteriores de la documentación. Es preferible reemplazar la página anterior con una actualización de html que redirige inmediatamente al espectador a la nueva página. Entonces, por ejemplo, nos movemos /doc/topic/old_info.rsta /doc/topic/new_info.rst. Eliminamos /doc/topic/old_info.rste /doc/topic/new_info.rstinsertamos una redirect-fromdirectiva que le dice a Sphinx que aún cree el archivo antiguo con la actualización/redireccionamiento de html (probablemente cerca de la parte superior del archivo para que se note)

.. redirect-from:: /topic/old_info

En los documentos creados, esto generará un archivo html /build/html/topic/old_info.htmlque tiene una actualización a new_info.html. Si los dos archivos están en diferentes subdirectorios:

.. redirect-from:: /old_topic/old_info2

producirá un archivo html /build/html/old_topic/old_info2.htmlque tiene una actualización (relativa) a ../topic/new_info.html.

Use la ruta completa para esta directiva, relativa a la raíz del documento en https://matplotlib.org/stable/. Así /old_topic/old_info2lo encontrarían los usuarios en http://matplotlib.org/stable/old_topic/old_info2. Para mayor claridad, no utilice enlaces relativos.

Agregando animaciones #

Sphinx-gallery extrae automáticamente las animaciones. Si esto no se desea, también hay una cuenta Matplotlib de Google/Gmail con nombre de usuario mplgithub que se usó para configurar la cuenta de github pero que se puede usar para otros fines, como alojar documentos de Google o videos de Youtube. Puede incrustar una animación de Matplotlib en los documentos guardando primero la animación como una película usando matplotlib.animation.Animation.save()y luego subiéndola al canal de Youtube de Matplotlib e insertando la cadena de incrustación que youtube proporciona como:

.. raw:: html

   <iframe width="420" height="315"
     src="https://www.youtube.com/embed/32cjc6V0OZY"
     frameborder="0" allowfullscreen>
   </iframe>

Un comando de guardar de ejemplo para generar una película se ve así

ani = animation.FuncAnimation(fig, animate, np.arange(1, len(y)),
    interval=25, blit=True, init_func=init)

ani.save('double_pendulum.mp4', fps=15)

Comuníquese con Michael Droettboom para obtener la contraseña de inicio de sesión para cargar videos de YouTube de Google Docs en la cuenta de mplgithub.

Generando diagramas de herencia #

Los diagramas de herencia de clases se pueden generar con la directiva de diagrama de herencia de Sphinx.

Ejemplo:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2
Diagrama de herencia de matplotlib.patches, matplotlib.lines, matplotlib.text