Rédaction de documents #

Mise en route #

Structure générale des fichiers #

Toute la documentation est construite à partir du doc/. Le doc/ répertoire contient les fichiers de configuration pour les fichiers Sphinx et reStructuredText ( ReST ; .rst) qui sont rendus dans les pages de documentation.

La documentation est créée de trois manières. Tout d'abord, la documentation de l'API ( doc/api) est créée par Sphinx à partir des docstrings des classes de la bibliothèque Matplotlib. À l'exception de doc/api/api_changes/, .rstles fichiers dans doc/apisont créés lors de la construction de la documentation. Voir Écrire des docstrings ci-dessous.

Deuxièmement, le contenu de doc/plot_types, doc/galleryet doc/tutorialsest généré par la galerie Sphinx à partir de fichiers python dans plot_types/, examples/et tutorials/. Ces sources consistent en des scripts python qui ont une documentation ReST intégrée dans leurs commentaires. Voir Écrire des exemples et des tutoriels ci-dessous.

Troisièmement, Matplotlib contient des documents narratifs écrits en ReST dans des sous-répertoires de doc/users/. Si vous souhaitez ajouter une nouvelle documentation adaptée à un .rstfichier plutôt qu'à un exemple de galerie ou de didacticiel, choisissez un sous-répertoire approprié pour le placer et ajoutez le fichier à la table des matières du index.rstsous-répertoire. Voir Écrire des pages ReST ci-dessous.

Noter

Ne modifiez pas directement les .rstfichiers dans doc/plot_types, doc/gallery, doc/tutorialset doc/api (sauf doc/api/api_changes/). Sphinx régénère les fichiers dans ces répertoires lors de la construction de la documentation.

Configuration de la construction de la doc #

La documentation de Matplotlib est générée à partir de reStructuredText ( ReST ) à l'aide de l' outil de génération de documentation Sphinx .

Pour construire la documentation, vous devrez configurer Matplotlib pour le développement . Notez en particulier les dépendances supplémentaires nécessaires à la construction de la documentation.

Construire les docs #

Les sources de documentation se trouvent dans le doc/répertoire du tronc. Le fichier de configuration pour Sphinx est doc/conf.py. Il contrôle les répertoires analysés par Sphinx, la manière dont les documents sont construits et la manière dont les extensions sont utilisées. Pour construire la documentation au format html, cd dans doc/et exécutez :

make html

D'autres invocations utiles incluent

# 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 définie sur par défaut pour générer les documents complets, mais quittez avec le statut de sortie 1 s'il y a des avertissements. Pour le désactiver, utilisez-W --keep-going

make SPHINXOPTS= html

Vous pouvez utiliser la Ovariable pour définir des options supplémentaires :

  • make O=-j4 htmlexécute une construction parallèle avec 4 processus.

  • make O=-Dplot_formats=png:100 htmlenregistre les chiffres en basse résolution.

  • make O=-Dplot_gallery=0 htmlignore la construction de la galerie.

Plusieurs options peuvent être combinées, par exemple .make O='-j4 -Dplot_gallery=0' html

Sous Windows, définissez les options en tant que variables d'environnement, par exemple :

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

Affichage des documents construits localement #

Les docs construites sont disponibles dans le dossier build/html. Un raccourci pour les ouvrir dans votre navigateur par défaut est :

make show

Écrire des pages ReST #

La plupart de la documentation se trouve soit dans les docstrings de classes et de méthodes individuelles, soit dans des .rstfichiers explicites, soit dans des exemples et des didacticiels. Tous ces éléments utilisent la syntaxe ReST et sont traités par Sphinx .

Le Sphinx reStructuredText Primer est une bonne introduction à l'utilisation de ReST. Des informations plus complètes sont disponibles dans la documentation de référence de reStructuredText .

Cette section contient des informations supplémentaires et des conventions sur l'utilisation de ReST dans la documentation Matplotlib.

Conventions de formatage et de style #

Il est utile de rechercher la cohérence dans la documentation de Matplotlib. Voici quelques conventions de formatage et de style utilisées.

Formatage de section #

Pour tout sauf les chapitres de niveau supérieur, utilisez pour les titres de section, par exemple, plutôt queUpper lowerPossible hangupsPossible Hangups

Notre objectif est de suivre les recommandations de la documentation Python et de la documentation Sphinx reStructuredText pour les caractères de balisage de section, c'est-à-dire :

  • #avec surlignement, pour les pièces. Ceci est réservé au titre principal dans index.rst. Toutes les autres pages doivent commencer par "chapitre" ou moins.

  • *avec surlignement, pour les chapitres

  • =, pour les tronçons

  • -, pour les sous-sections

  • ^, pour les sous-sous-sections

  • ", pour les paragraphes

Cela peut ne pas encore être appliqué de manière cohérente dans les documents existants.

Arguments de la fonction #

Les arguments de fonction et les mots clés dans les docstrings doivent être référencés à l'aide du *emphasis*rôle. Cela gardera la documentation de Matplotlib cohérente avec la documentation de Python :

Here is a description of *argument*

N'utilisez pas le :`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 le ``literal``rôle :

Do not describe ``argument`` like this.

Se référant à d'autres documents et sections #

Sphinx permet des références internes entre les documents.

Les documents peuvent être liés à la :doc:directive :

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`

sera rendu comme :

Voir la mise en place

Voir le tutoriel Guide de démarrage rapide

Voir l'exemple Tracé simple

Les sections peuvent également recevoir des noms de référence. Par exemple à partir du lien Installation :

.. _clean-install:

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

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

et faites-y référence en utilisant la syntaxe de référence standard :

See :ref:`clean-install`

donnera le lien suivant : Comment supprimer complètement Matplotlib

Pour optimiser la cohérence interne de l'étiquetage et des références de section, utilisez des étiquettes descriptives séparées par des tirets pour les références de section. Gardez à l'esprit que le contenu peut être réorganisé ultérieurement, évitez donc les noms de niveau supérieur dans les références comme userou devel ou faqsauf si nécessaire, car par exemple la FAQ "qu'est-ce qu'un backend?" pourrait plus tard faire partie du guide de l'utilisateur, donc l'étiquette :

.. _what-is-a-backend:

est mieux que:

.. _faq-backend:

De plus, comme les traits de soulignement sont largement utilisés par Sphinx lui-même, utilisez des traits d'union pour séparer les mots.

Se référant à un autre numéro de code

Pour créer un lien vers d'autres méthodes, classes ou modules dans Matplotlib, vous pouvez utiliser des back ticks, par exemple :

`matplotlib.collections.LineCollection`

génère un lien comme celui-ci : matplotlib.collections.LineCollection.

Remarque : Nous utilisons le paramètre sphinx afin que vous n'ayez pas à utiliser des qualificatifs tels que , , etc.default_role = 'obj':class::func::meth:

Souvent, vous ne souhaitez pas afficher le nom complet du package et du module. Tant que la cible est sans ambiguïté, vous pouvez simplement les laisser de côté :

`.LineCollection`

et le lien fonctionne toujours : LineCollection.

S'il existe plusieurs éléments de code portant le même nom (par exemple plot(), une méthode dans plusieurs classes), vous devrez étendre la définition :

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

Ceux-ci apparaîtront comme pyplot.plotou Axes.plot. Pour toujours afficher uniquement le dernier segment, vous pouvez ajouter un tilde comme préfixe :

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

sera rendu comme plotou plot.

D'autres forfaits peuvent également être liés via intersphinx :

`numpy.mean`

renverra ce lien: numpy.mean. Cela fonctionne pour Python, Numpy, Scipy et Pandas (la liste complète est dans doc/conf.py). Si la liaison externe échoue, vous pouvez vérifier la liste complète des objets référençables avec les commandes suivantes :

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'

Y compris les chiffres et les fichiers #

Les fichiers image peuvent être directement inclus dans les pages avec la image::directive. par exemple, tutorials/intermediate/constrainedlayout_guide.pyaffiche quelques images statiques :

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

Les fichiers peuvent être inclus textuellement. Par exemple, le LICENSEfichier est inclus dans le contrat de licence en utilisant

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

Le répertoire d'exemples est copié doc/gallerypar sphinx-gallery, de sorte que les tracés du répertoire d'exemples peuvent être inclus à l'aide de

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

Notez qu'il est fait référence au script python qui génère le tracé, plutôt qu'à tout tracé créé. Sphinx-gallery fournira la référence correcte lors de la construction de la documentation.

Rédaction de docstrings #

La plupart de la documentation de l'API est écrite en docstrings. Ce sont des blocs de commentaires dans le code source qui expliquent le fonctionnement du code.

Noter

Certaines parties de la documentation ne sont pas encore conformes au style de documentation actuel. En cas de doute, suivez les règles données ici et non ce que vous pouvez voir dans le code source. Les demandes d'extraction mettant à jour les docstrings au style actuel sont les bienvenues.

Toutes les docstrings nouvelles ou modifiées doivent être conformes au guide numpydoc docstring . Une grande partie de la syntaxe ReST discutée ci-dessus ( Écrire des pages ReST ) peut être utilisée pour les liens et les références. Ces docstrings finissent par remplir le doc/apirépertoire et forment la documentation de référence de la bibliothèque.

Exemple de chaîne de documentation #

Un exemple de docstring ressemble à :

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
    """

Voir la hlinesdocumentation pour savoir comment cela s'affiche.

Le site Web de Sphinx contient également de nombreux documents concernant le balisage ReST et l'utilisation de Sphinx en général.

Conventions de formatage #

Les conventions de base de docstring sont couvertes dans le guide numpydoc docstring et la documentation Sphinx . Quelques conventions de formatage spécifiques à Matplotlib à garder à l'esprit :

Postes de devis #

Les guillemets pour les docstrings à une seule ligne sont sur la même ligne (pydocstyle D200):

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

Les guillemets pour les docstrings multi-lignes sont sur des lignes séparées (pydocstyle D213) :

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

[...]
"""

Arguments de la fonction #

Les arguments de fonction et les mots clés dans les docstrings doivent être référencés à l'aide du *emphasis*rôle. Cela gardera la documentation de Matplotlib cohérente avec la documentation de Python :

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

N'utilisez pas le ou le rôle :`default role```literal``

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

Citations pour les chaînes #

Matplotlib n'a pas de convention d'utilisation des guillemets simples ou des guillemets doubles. Il y a un mélange des deux dans le code actuel.

Utilisez des guillemets simples ou doubles lorsque vous donnez des valeurs de chaîne, par exemple

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

No ``'extra'`` literal quotes.

L'utilisation de guillemets littéraux supplémentaires autour du texte est déconseillée. Bien qu'ils améliorent légèrement les documents rendus, ils sont lourds à taper et difficiles à lire dans les documents en texte brut.

Descriptions des types de paramètres #

L'objectif principal des descriptions de types de paramètres est d'être lisibles et compréhensibles par les humains. Si les types possibles sont trop complexes, utilisez une simplification pour la description du type et expliquez le type plus précisément dans le texte.

Généralement, les conventions du guide numpydoc docstring s'appliquent. Les règles suivantes les développent là où les conventions numpydoc ne sont pas spécifiques.

À utiliser floatpour un type qui peut être n'importe quel nombre.

Utilisez pour décrire une position 2D. Les parenthèses doivent être incluses pour rendre le tuple-ness plus évident.(float, float)

À utiliser array-likepour les séquences numériques homogènes, qui peuvent généralement être un numpy.array. La dimensionnalité peut être spécifiée à l'aide 2Dde , 3D, n-dimensional. Si vous avez besoin d'avoir des variables indiquant les tailles des dimensions, utilisez des lettres majuscules entre parenthèses ( ). Lorsque vous y faites référence dans le texte, ils sont plus faciles à lire et aucune mise en forme spéciale n'est nécessaire. Utilisez à la place de pour les types de retour si l'objet retourné est en effet un tableau numpy.(M, N) array-likearrayarray-like

floatest le dtype implicite par défaut pour les array-likes. Pour les autres dtypes, utilisez .array-like of int

Quelques utilisations possibles :

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

Les séquences homogènes non numériques sont décrites sous forme de listes, par exemple :

list of str
list of `.Artist`

Types de références #

En règle générale, les règles de référence à un autre code s'appliquent. Plus précisement:

Utilisez des références complètes `~matplotlib.colors.Normalize`avec une abréviation tilde dans les types de paramètres. Alors que le nom complet aide le lecteur de docstrings en texte brut, le HTML n'a pas besoin d'afficher le nom complet car il y est lié. Par conséquent, le ~-raccourcissement le rend plus lisible.

Utilisez des liens abrégés `.Normalize`dans le texte.

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

Valeurs par défaut #

Contrairement au guide numpydoc, les paramètres n'ont pas besoin d'être marqués comme facultatifs s'ils ont une simple valeur par défaut :

  • utiliser lorsque cela est possible.{name} : {type}, default: {val}

  • utilisez et décrivez la valeur par défaut dans le texte si elle ne peut pas être suffisamment expliquée de la manière recommandée.{name} : {type}, optional

La valeur par défaut doit fournir des informations sémantiques destinées à un lecteur humain. Dans les cas simples, il reformule la valeur dans la signature de la fonction. Le cas échéant, des unités doivent être ajoutées.

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

Si Aucun n'est utilisé que comme valeur sentinelle pour "paramètre non spécifié", ne le documentez pas comme valeur par défaut. Selon le contexte, indiquez la valeur par défaut réelle ou marquez le paramètre comme facultatif si le fait de ne pas le spécifier n'a aucun effet particulier.

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 alsorubriques #

Sphinx relie automatiquement les éléments de code dans les blocs de définition des sections. Pas besoin d'utiliser des backticks ici:See also

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

Emballage des listes de paramètres #

Les longues listes de paramètres doivent être enveloppées à l'aide d'un \for continuation et en commençant sur la nouvelle ligne sans aucun retrait (pas de retrait car pydoc analysera la docstring et supprimera la continuation de la ligne afin que le retrait entraîne beaucoup d'espaces blancs dans la ligne):

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

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

    ...
    """

Alternativement, vous pouvez décrire les valeurs de paramètre valides dans une section dédiée de la docstring.

rcParams #

rcParams peut être référencé avec le :rc:rôle personnalisé : :rc:`foo`yields , qui est un lien vers la description du fichier.rcParams["foo"] = 'default'matplotlibrc

Setters et getters #

Les propriétés d'artiste sont implémentées à l'aide de méthodes setter et getter (car Matplotlib est antérieur au propertydécorateur Python). Par convention, ces setters et getters sont nommés set_PROPERTYNAMEet get_PROPERTYNAME; la liste des propriétés ainsi définies sur un artiste et leurs valeurs peuvent être listées par les fonctions setpet getp.

Le bloc Paramètres des méthodes de définition de propriétés est analysé pour documenter les valeurs acceptées, par exemple la docstring de Line2D.set_linestylecommence par

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

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

qui se traduit par la ligne suivante dans la sortie de plt.setp(line)ou :plt.setp(line, "linestyle")

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

Dans certains cas rares (principalement, les setters qui acceptent à la fois un tuple unique et un tuple non compressé), les valeurs acceptées ne peuvent pas être documentées de cette manière ; dans ce cas, ils peuvent être documentés sous forme de bloc, par exemple pour :.. 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.
    """

Notez que le début ..fait du bloc un commentaire reST, le cachant des documents rendus... ACCEPTS:

Arguments de mots-clés #

Noter

Les informations contenues dans cette section sont activement discutées par l'équipe de développement, utilisez donc l'interpolation docstring uniquement si nécessaire. Cette section a été laissée en place pour le moment car cette interpolation fait partie de la documentation existante.

Étant donné que Matplotlib utilise beaucoup de pass-through kwargs, par exemple, dans chaque fonction qui crée une ligne ( plot, semilogx, semilogy, etc.), il peut être difficile pour le nouvel utilisateur de savoir lesquels kwargssont pris en charge. Matplotlib utilise un schéma d'interpolation de docstring pour prendre en charge la documentation de chaque fonction qui prend un fichier **kwargs. Les exigences sont :

  1. un seul point de configuration afin que les modifications apportées aux propriétés ne nécessitent pas plusieurs modifications de docstring.

  2. aussi automatisé que possible afin que, à mesure que les propriétés changent, les documents soient mis à jour automatiquement.

Le @_docstring.interpddécorateur met cela en œuvre. Toute fonction acceptant le Line2Dpass-through kwargs, par exemple , matplotlib.axes.Axes.plotpeut répertorier un résumé des Line2Dpropriétés, comme suit :

# 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)syntaxe fait interpdrechercher une sous- Artistclasse nommée Line2Det appelle artist.kwdoccette classe. artist.kwdoc introspecte la sous-classe et résume ses propriétés en tant que sous-chaîne, qui est interpolée dans la docstring.

Notez que ce schéma ne fonctionne pas pour décorer un Artist's __init__, car la sous-classe et ses propriétés ne sont pas encore définies à ce stade. Au lieu de cela, @_docstring.interpdpeut être utilisé pour décorer la classe elle-même - à ce stade, kwdocpeut répertorier les propriétés et les interpoler dans __init__.__doc__.

Héritage des docstrings #

Si une sous-classe remplace une méthode mais ne change pas la sémantique, nous pouvons réutiliser la docstring parent pour la méthode de la classe enfant. Python le fait automatiquement, si la méthode de la sous-classe n'a pas de docstring.

Utilisez un commentaire simple pour indiquer l'intention de réutiliser la docstring parent. De cette façon, nous ne créons pas accidentellement une docstring à l'avenir :# docstring inherited

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

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

Ajouter des chiffres #

Comme ci-dessus (voir Inclure des figures et des fichiers ), les figures de la galerie d'exemples peuvent être référencées avec une directive pointant vers le script python qui a créé la figure. Par exemple, la docstring fait référence au fichier :.. plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

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

Notez que cela examples/text_labels_and_annotations/legend.pya été mappé sur gallery/text_labels_and_annotations/legend.py, une redirection qui pourrait être corrigée lors d'une future réorganisation de la documentation.

Les tracés peuvent également être placés directement dans les docstrings. Les détails sont dans matplotlib.sphinxext.plot_directive . Un court exemple est :

"""
...

Examples
--------

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

Un avantage de ce style par rapport à la référence à un exemple de script est que le code apparaîtra également dans les docstrings interactifs.

Rédaction d'exemples et de tutoriels #

Les exemples et les tutoriels sont des scripts python qui sont exécutés par Sphinx Gallery pour créer une galerie d'images dans les répertoires /doc/galleryet /doc/tutorialsrespectivement. Pour exclure un exemple de la génération d'un tracé, insérez "sgskip" quelque part dans le nom du fichier.

Le format de ces fichiers est relativement simple. Les blocs de commentaires correctement formatés sont traités comme du texte ReST , le code est affiché et les chiffres sont placés dans la page construite.

Par exemple, l'exemple Exemple de tracé simple est généré à partir de /examples/lines_bars_and_markers/simple_plot.py, qui ressemble à :

"""
===========
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()

Le premier bloc de commentaire est traité comme du texte ReST . Les autres blocs de commentaires s'affichent sous forme de commentaires dans Simple Plot .

Les didacticiels sont créés avec exactement le même mécanisme, sauf qu'ils sont plus longs et comportent généralement plus d'un bloc de commentaires (c.- à-d. Guide de démarrage rapide ). Le premier bloc de commentaires peut être le même que dans l'exemple ci-dessus. Les blocs suivants de texte ReST sont délimités par une ligne de ###caractères :

"""
===========
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 cette manière, le texte, le code et les chiffres sont sortis dans un style "carnet".

Divers #

Documents de déménagement #

Parfois, il est souhaitable de déplacer ou de consolider la documentation. Sans action, cela conduira à des liens morts (404) ou pointant vers d'anciennes versions de la documentation. Il est préférable de remplacer l'ancienne page par une actualisation html qui redirige immédiatement le spectateur vers la nouvelle page. Ainsi, par exemple, nous passons /doc/topic/old_info.rstà /doc/topic/new_info.rst. Nous supprimons /doc/topic/old_info.rstet /doc/topic/new_info.rstinsérons une redirect-fromdirective qui indique à sphinx de continuer à créer l'ancien fichier avec l'actualisation/la redirection html (probablement vers le haut du fichier pour le rendre visible)

.. redirect-from:: /topic/old_info

Dans les documents construits, cela donnera un fichier html /build/html/topic/old_info.htmlqui a une actualisation vers new_info.html. Si les deux fichiers se trouvent dans des sous-répertoires différents :

.. redirect-from:: /old_topic/old_info2

donnera un fichier html /build/html/old_topic/old_info2.htmlqui a une actualisation (relative) en ../topic/new_info.html.

Utilisez le chemin d'accès complet pour cette directive, par rapport à la racine de la documentation à https://matplotlib.org/stable/. Serait donc /old_topic/old_info2trouvé par les utilisateurs à http://matplotlib.org/stable/old_topic/old_info2. Pour plus de clarté, n'utilisez pas de liens relatifs.

Ajouter des animations #

Les animations sont récupérées automatiquement par Sphinx-gallery. Si cela n'est pas souhaité, il existe également un compte Matplotlib Google/Gmail avec nom d'utilisateur mplgithub qui a été utilisé pour configurer le compte github mais peut être utilisé à d'autres fins, comme l'hébergement de documents Google ou de vidéos Youtube. Vous pouvez intégrer une animation Matplotlib dans la documentation en enregistrant d'abord l'animation en tant que film à l'aide de matplotlib.animation.Animation.save(), puis en la téléchargeant sur la chaîne Youtube de Matplotlib et en insérant la chaîne d'intégration que youtube fournit comme :

.. raw:: html

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

Un exemple de commande de sauvegarde pour générer un film ressemble à ceci

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

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

Contactez Michael Droettboom pour le mot de passe de connexion pour télécharger des vidéos youtube de google docs sur le compte mplgithub.

Génération de diagrammes d'héritage #

Les diagrammes d'héritage de classe peuvent être générés avec la directive Sphinx heritage-diagram .

Exemple:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2
Diagramme d'héritage de matplotlib.patches, matplotlib.lines, matplotlib.text