Scrivere la documentazione #

Per iniziare #

Struttura generale dei file #

Tutta la documentazione è costruita dal file doc/. La doc/ directory contiene i file di configurazione per i file Sphinx e reStructuredText ( ReST ; .rst) che vengono visualizzati nelle pagine della documentazione.

La documentazione viene creata in tre modi. Innanzitutto, la documentazione API ( doc/api) viene creata da Sphinx dalle docstring delle classi nella libreria Matplotlib. Ad eccezione di doc/api/api_changes/, .rsti file in doc/apivengono creati quando viene compilata la documentazione. Vedi Scrivere docstring sotto.

In secondo luogo, i contenuti di doc/plot_types, doc/gallerye doc/tutorialssono generati dalla Sphinx Gallery dai file python in plot_types/, examples/e tutorials/. Queste fonti sono costituite da script Python che hanno la documentazione ReST incorporata nei loro commenti. Vedi Esempi di scrittura e tutorial di seguito.

Terzo, Matplotlib ha documenti narrativi scritti in ReST nelle sottodirectory di doc/users/. Se desideri aggiungere nuova documentazione adatta a un .rstfile piuttosto che a una galleria oa un esempio di tutorial, scegli una sottodirectory appropriata in cui inserirla e aggiungi il file all'indice della index.rstsottodirectory. Vedi Scrivere pagine ReST sotto.

Nota

Non modificare direttamente i .rstfile in doc/plot_types, doc/gallery, doc/tutorialse doc/api (eccetto doc/api/api_changes/). Sphinx rigenera i file in queste directory durante la creazione della documentazione.

Configurazione della build del documento n.

La documentazione per Matplotlib viene generata da reStructuredText ( ReST ) utilizzando lo strumento di generazione della documentazione Sphinx .

Per creare la documentazione sarà necessario configurare Matplotlib per lo sviluppo . Si noti in particolare le dipendenze aggiuntive richieste per costruire la documentazione.

Costruire i documenti #

Le fonti della documentazione si trovano nella doc/directory nel bagagliaio. Il file di configurazione per Sphinx è doc/conf.py. Controlla quali directory Sphinx analizza, come vengono creati i documenti e come vengono utilizzate le estensioni. Per creare la documentazione in formato html, eseguire il cd doc/ed eseguire:

make html

Altre invocazioni utili includono

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

# Build pdf docs.
make latexpdf

La SPHINXOPTSvariabile è impostata per impostazione predefinita per creare i documenti completi ma esce con lo stato di uscita 1 se sono presenti avvisi. Per disimpostarlo, utilizzare-W --keep-going

make SPHINXOPTS= html

È possibile utilizzare la Ovariabile per impostare opzioni aggiuntive:

  • make O=-j4 htmlesegue una build parallela con 4 processi.

  • make O=-Dplot_formats=png:100 htmlsalva le figure in bassa risoluzione.

  • make O=-Dplot_gallery=0 htmlsalta la costruzione della galleria.

È possibile combinare più opzioni, ad es .make O='-j4 -Dplot_gallery=0' html

Su Windows, imposta le opzioni come variabili di ambiente, ad esempio:

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

Visualizzazione di documenti creati localmente #

I documenti creati sono disponibili nella cartella build/html. Una scorciatoia per aprirli nel browser predefinito è:

make show

Scrivere pagine ReST #

La maggior parte della documentazione si trova nelle docstring di singole classi e metodi, in .rstfile espliciti o in esempi e tutorial. Tutti questi utilizzano la sintassi ReST e vengono elaborati da Sphinx .

Sphinx reStructuredText Primer è una buona introduzione all'utilizzo di ReST. Informazioni più complete sono disponibili nella documentazione di riferimento reStructuredText .

Questa sezione contiene ulteriori informazioni e convenzioni sull'utilizzo di ReST nella documentazione di Matplotlib.

Convenzioni di formattazione e stile #

È utile cercare la coerenza nella documentazione di Matplotlib. Di seguito sono riportate alcune convenzioni di formattazione e stile utilizzate.

Formattazione della sezione #

Per tutto tranne i capitoli di primo livello, usa per i titoli delle sezioni, ad esUpper lowerPossible hangupsPossible Hangups

Miriamo a seguire le raccomandazioni della documentazione Python e della documentazione Sphinx reStructuredText per i caratteri di markup di sezione, ad esempio:

  • #con sopralineatura, per parti. Questo è riservato al titolo principale in index.rst. Tutte le altre pagine dovrebbero iniziare con "capitolo" o inferiore.

  • *con sopralineatura, per i capitoli

  • =, per sezioni

  • -, per le sottosezioni

  • ^, per le sottosottosezioni

  • ", per i paragrafi

Questo potrebbe non essere ancora applicato in modo coerente nei documenti esistenti.

Argomenti della funzione #

Gli argomenti della funzione e le parole chiave all'interno delle docstring dovrebbero essere riferiti usando il *emphasis*ruolo. Ciò manterrà la documentazione di Matplotlib coerente con la documentazione di Python:

Here is a description of *argument*

Non utilizzare il :`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.

né il ``literal``ruolo:

Do not describe ``argument`` like this.

Riferimenti ad altri documenti e sezioni #

Sphinx consente riferimenti interni tra i documenti.

I documenti possono essere collegati alla :doc:direttiva:

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`

renderà come:

Vedere l' installazione

Guarda il tutorial Guida di avvio rapido

Vedi l'esempio Plot semplice

Alle sezioni possono anche essere assegnati nomi di riferimento. Ad esempio dal link di installazione :

.. _clean-install:

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

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

e fare riferimento ad esso utilizzando la sintassi di riferimento standard:

See :ref:`clean-install`

fornirà il seguente collegamento: Come rimuovere completamente Matplotlib

Per massimizzare la coerenza interna nell'etichettatura e nei riferimenti delle sezioni, utilizzare etichette descrittive separate da trattini per i riferimenti delle sezioni. Tieni presente che i contenuti potrebbero essere riorganizzati in seguito, quindi evita nomi di primo livello nei riferimenti come usero devel o faqa meno che non sia necessario, perché ad esempio la FAQ "cos'è un backend?" potrebbe in seguito diventare parte della guida per gli utenti, quindi l'etichetta:

.. _what-is-a-backend:

è meglio di:

.. _faq-backend:

Inoltre, poiché i caratteri di sottolineatura sono ampiamente utilizzati dalla stessa Sphinx, utilizzare i trattini per separare le parole.

Riferito ad altro codice #

Per collegarti ad altri metodi, classi o moduli in Matplotlib puoi utilizzare i back tick, ad esempio:

`matplotlib.collections.LineCollection`

genera un collegamento come questo: matplotlib.collections.LineCollection.

Nota: utilizziamo l'impostazione sphinx in modo da non dover utilizzare qualificatori come , e simili.default_role = 'obj':class::func::meth:

Spesso non vuoi mostrare il pacchetto completo e il nome del modulo. Finché l'obiettivo non è ambiguo, puoi semplicemente lasciarli fuori:

`.LineCollection`

e il link funziona ancora: LineCollection.

Se ci sono più elementi di codice con lo stesso nome (ad esempio plot()è un metodo in più classi), dovrai estendere la definizione:

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

Questi verranno visualizzati come pyplot.ploto Axes.plot. Per mostrare ancora solo l'ultimo segmento puoi aggiungere una tilde come prefisso:

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

renderà come ploto plot.

Altri pacchetti possono anche essere collegati tramite intersphinx :

`numpy.mean`

restituirà questo link: numpy.mean. Funziona con Python, Numpy, Scipy e Pandas (l'elenco completo è in doc/conf.py). Se il collegamento esterno fallisce, puoi controllare l'elenco completo degli oggetti referenziabili con i seguenti comandi:

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'

Comprese figure e file #

I file immagine possono essere inclusi direttamente nelle pagine con la image::direttiva. ad esempio, tutorials/intermediate/constrainedlayout_guide.pyvisualizza un paio di immagini statiche:

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

I file possono essere inclusi alla lettera. Ad esempio, il LICENSEfile è incluso nel contratto di licenza utilizzando

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

La directory degli esempi viene copiata doc/galleryda sphinx-gallery, quindi i grafici dalla directory degli esempi possono essere inclusi utilizzando

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

Si noti che si fa riferimento allo script python che genera la trama, piuttosto che a qualsiasi trama creata. Sphinx-gallery fornirà il riferimento corretto quando la documentazione sarà compilata.

Scrivere docstring #

La maggior parte della documentazione API è scritta in docstring. Questi sono blocchi di commenti nel codice sorgente che spiegano come funziona il codice.

Nota

Alcune parti della documentazione non sono ancora conformi allo stile della documentazione attuale. In caso di dubbio, segui le regole fornite qui e non ciò che potresti vedere nel codice sorgente. Le pull request che aggiornano le docstring allo stile corrente sono molto gradite.

Tutte le docstring nuove o modificate devono essere conformi alla numpydoc docstring guide . Gran parte della sintassi ReST discussa sopra ( Scrittura di pagine ReST ) può essere utilizzata per collegamenti e riferimenti. Queste docstring alla fine popolano la doc/apidirectory e formano la documentazione di riferimento per la libreria.

Esempio di stringa di documentazione #

Una docstring di esempio è simile a:

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

Vedi la hlinesdocumentazione per come questo rende.

Il sito Web Sphinx contiene anche molta documentazione relativa al markup ReST e al lavoro con Sphinx in generale.

Convenzioni di formattazione #

Le convenzioni di base sulle docstring sono trattate nella guida numpydoc docstring e nella documentazione di Sphinx . Alcune convenzioni di formattazione specifiche di Matplotlib da tenere a mente:

Quota posizioni #

Le virgolette per le docstring a riga singola sono sulla stessa riga (pydocstyle D200):

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

Le virgolette per le docstring multilinea sono su righe separate (pydocstyle D213):

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

[...]
"""

Argomenti della funzione #

Gli argomenti della funzione e le parole chiave all'interno delle docstring dovrebbero essere riferiti usando il *emphasis*ruolo. Ciò manterrà la documentazione di Matplotlib coerente con la documentazione di Python:

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

Non utilizzare il o il ruolo:`default role```literal``

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

Citazioni per stringhe #

Matplotlib non ha una convenzione se utilizzare virgolette singole o virgolette doppie. C'è una combinazione di entrambi nel codice attuale.

Usa semplici virgolette singole o doppie quando fornisci valori di stringa, ad es

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

No ``'extra'`` literal quotes.

L'uso di virgolette extra letterali attorno al testo è sconsigliato. Mentre migliorano leggermente i documenti renderizzati, sono ingombranti da digitare e difficili da leggere nei documenti di testo normale.

Descrizioni del tipo di parametro #

L'obiettivo principale per le descrizioni dei tipi di parametro è essere leggibili e comprensibili dagli esseri umani. Se i tipi possibili sono troppo complessi, utilizzare una semplificazione per la descrizione del tipo e spiegare il tipo in modo più preciso nel testo.

In generale, si applicano le convenzioni della guida docstring numpydoc . Le seguenti regole si espandono su di esse dove le convenzioni numpydoc non sono specifiche.

Utilizzare floatper un tipo che può essere qualsiasi numero.

Utilizzare per descrivere una posizione 2D. Le parentesi dovrebbero essere incluse per rendere la tupla più ovvia.(float, float)

Utilizzare array-likeper sequenze numeriche omogenee, che in genere potrebbero essere un numpy.array. La dimensionalità può essere specificata usando 2D, 3D, n-dimensional. Se è necessario disporre di variabili che indichino le dimensioni delle dimensioni, utilizzare le lettere maiuscole tra parentesi ( ). Quando ci si fa riferimento nel testo, sono più facili da leggere e non è necessaria alcuna formattazione speciale. Utilizzare invece di per i tipi restituiti se l'oggetto restituito è effettivamente un array numpy.(M, N) array-likearrayarray-like

floatè il dtype predefinito implicito per gli array-like. Per altri dtype usa .array-like of int

Alcuni possibili utilizzi:

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

Le sequenze omogenee non numeriche sono descritte come elenchi, ad esempio:

list of str
list of `.Artist`

Tipi di riferimento #

In generale, si applicano le regole del riferimento ad altro codice . Più specificamente:

Utilizzare riferimenti completi `~matplotlib.colors.Normalize`con un'abbreviazione tilde nei tipi di parametro. Mentre il nome completo aiuta il lettore di docstring in testo semplice, l'HTML non ha bisogno di mostrare il nome completo poiché si collega ad esso. Quindi, l' ~accorciamento lo rende più leggibile.

Usa collegamenti abbreviati `.Normalize`nel testo.

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

Valori predefiniti #

A differenza della guida numpydoc, i parametri non devono essere contrassegnati come facoltativi se hanno un semplice valore predefinito:

  • utilizzare quando possibile.{name} : {type}, default: {val}

  • utilizzare e descrivere l'impostazione predefinita nel testo se non può essere spiegata a sufficienza nel modo consigliato.{name} : {type}, optional

Il valore predefinito dovrebbe fornire informazioni semantiche mirate a un lettore umano. In casi semplici, riformula il valore nella firma della funzione. Se applicabile, le unità dovrebbero essere aggiunte.

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

Se None viene utilizzato solo come valore sentinella per "parametro non specificato", non documentarlo come predefinito. A seconda del contesto, indicare il valore predefinito effettivo o contrassegnare il parametro come facoltativo se la mancata specificazione non ha effetti particolari.

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

Sphinx collega automaticamente gli elementi di codice nei blocchi di definizione delle sezioni. Non c'è bisogno di usare i backtick lì:See also

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

Elenchi di parametri di wrapping #

Gli elenchi di parametri lunghi dovrebbero essere racchiusi usando una \continuazione for e iniziando sulla nuova riga senza alcun rientro (nessun rientro perché pydoc analizzerà la docstring e rimuoverà la continuazione della riga in modo che il rientro provochi molti spazi bianchi all'interno della riga):

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

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

    ...
    """

In alternativa, puoi descrivere i valori dei parametri validi in una sezione dedicata della docstring.

rcParams #

È possibile fare riferimento a rcParams con il :rc:ruolo personalizzato: :rc:`foo`yields , che è un collegamento alla descrizione del file.rcParams["foo"] = 'default'matplotlibrc

Setter e getter #

Le proprietà dell'artista sono implementate utilizzando i metodi setter e getter (poiché Matplotlib precede il propertydecoratore Python). Per convenzione, questi setter e getter sono denominati set_PROPERTYNAMEe get_PROPERTYNAME; l'elenco delle proprietà così definite su un artista ei loro valori possono essere elencati dalle funzioni setpe getp.

Il blocco Parameters dei metodi di impostazione delle proprietà viene analizzato per documentare i valori accettati, ad esempio la docstring di Line2D.set_linestyleinizia con

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

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

che si traduce nella seguente riga nell'output di plt.setp(line)o :plt.setp(line, "linestyle")

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

In alcuni rari casi (principalmente, setter che accettano sia una tupla singola che una tupla spacchettata), i valori accettati non possono essere documentati in questo modo; in tal caso, possono essere documentati come un blocco, ad esempio per :.. 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.
    """

Si noti che l'interlinea ..rende il blocco un commento resto, nascondendolo dai documenti visualizzati... ACCEPTS:

Argomenti parola chiave #

Nota

Le informazioni in questa sezione vengono attivamente discusse dal team di sviluppo, quindi utilizzare l'interpolazione docstring solo se necessario. Questa sezione è stata lasciata in vigore per ora perché questa interpolazione fa parte della documentazione esistente.

Dal momento che Matplotlib utilizza molti pass-through kwargs, ad esempio, in ogni funzione che crea una linea ( plot, semilogx, semilogy, ecc.), può essere difficile per il nuovo utente sapere quali kwargssono supportati. Matplotlib utilizza uno schema di interpolazione docstring per supportare la documentazione di ogni funzione che accetta un file **kwargs. I requisiti sono:

  1. singolo punto di configurazione in modo che le modifiche alle proprietà non richiedano più modifiche alla docstring.

  2. il più automatizzato possibile in modo che quando le proprietà cambiano, i documenti vengono aggiornati automaticamente.

Il @_docstring.interpddecoratore lo implementa. Qualsiasi funzione che accetta Line2Dpass-through kwargs, ad esempio , matplotlib.axes.Axes.plotpuò elencare un riepilogo delle Line2Dproprietà, come segue:

# 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)sintassi fa interpdcercare una Artistsottoclasse denominata Line2De chiama artist.kwdocquella classe. artist.kwdoc analizza la sottoclasse e riassume le sue proprietà come una sottostringa, che viene interpolata nella docstring.

Si noti che questo schema non funziona per decorare un Artist's __init__, poiché la sottoclasse e le sue proprietà non sono ancora definite a quel punto. Invece, @_docstring.interpdpuò essere utilizzato per decorare la classe stessa: a quel punto, kwdocpuò elencare le proprietà e interpolarle in __init__.__doc__.

Ereditare le docstring #

Se una sottoclasse sovrascrive un metodo ma non cambia la semantica, possiamo riutilizzare la docstring genitore per il metodo della classe figlia. Python lo fa automaticamente, se il metodo della sottoclasse non ha una docstring.

Usa un semplice commento per denotare l'intenzione di riutilizzare la docstring genitore. In questo modo non creiamo accidentalmente una docstring in futuro:# docstring inherited

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

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

Aggiunta di cifre #

Come sopra (vedi Includere figure e file ), le figure nella galleria di esempi possono essere referenziate con una direttiva che punta allo script python che ha creato la figura. Ad esempio, la docstring fa riferimento al file :.. plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

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

Si noti che examples/text_labels_and_annotations/legend.pyè stato mappato a gallery/text_labels_and_annotations/legend.py, un reindirizzamento che potrebbe essere risolto in una futura riorganizzazione dei documenti.

I grafici possono anche essere posizionati direttamente all'interno delle docstring. I dettagli sono in matplotlib.sphinxext.plot_directive . Un breve esempio è:

"""
...

Examples
--------

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

Un vantaggio di questo stile rispetto al riferimento a uno script di esempio è che il codice apparirà anche nelle docstring interattive.

Esempi di scrittura e tutorial #

Esempi e tutorial sono script Python che vengono eseguiti da Sphinx Gallery per creare una galleria di immagini nelle directory /doc/gallerye /doc/tutorialsrispettivamente. Per escludere un esempio dalla generazione di un grafico, inserire "sgskip" da qualche parte nel nome del file.

Il formato di questi file è relativamente semplice. I blocchi di commento correttamente formattati vengono trattati come testo ReST , il codice viene visualizzato e le figure vengono inserite nella pagina creata.

Ad esempio, l'esempio Simple Plot viene generato da /examples/lines_bars_and_markers/simple_plot.py, che assomiglia a:

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

Il primo blocco di commento viene trattato come testo ReST . Gli altri blocchi di commento vengono visualizzati come commenti in Simple Plot .

I tutorial sono realizzati con lo stesso identico meccanismo, tranne per il fatto che sono più lunghi e in genere hanno più di un blocco di commenti (es . Guida rapida ). Il primo blocco di commento può essere lo stesso dell'esempio precedente. I successivi blocchi di testo ReST sono delimitati da una riga di ###caratteri:

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

In questo modo testo, codice e figure vengono emessi in uno stile "taccuino".

Varie #

Documentazione in movimento #

A volte è desiderabile spostare o consolidare la documentazione. Senza alcuna azione ciò porterà alla morte dei collegamenti (404) o al puntamento a vecchie versioni della documentazione. È preferibile sostituire la vecchia pagina con un refresh html che reindirizzi immediatamente lo spettatore alla nuova pagina. Quindi, ad esempio, passiamo /doc/topic/old_info.rsta /doc/topic/new_info.rst. Rimuoviamo /doc/topic/old_info.rste /doc/topic/new_info.rstinseriamo una redirect-fromdirettiva che dice a sphinx di creare ancora il vecchio file con l'aggiornamento/reindirizzamento html al suo interno (probabilmente vicino alla parte superiore del file per renderlo evidente)

.. redirect-from:: /topic/old_info

Nei documenti compilati questo produrrà un file html /build/html/topic/old_info.htmlche ha un aggiornamento in new_info.html. Se i due file si trovano in sottodirectory diverse:

.. redirect-from:: /old_topic/old_info2

produrrà un file html /build/html/old_topic/old_info2.htmlche ha un aggiornamento (relativo) a ../topic/new_info.html.

Utilizzare il percorso completo per questa direttiva, relativo alla radice del documento in https://matplotlib.org/stable/. Quindi /old_topic/old_info2sarebbe stato trovato dagli utenti di http://matplotlib.org/stable/old_topic/old_info2. Per chiarezza, non utilizzare collegamenti relativi.

Aggiunta di animazioni #

Le animazioni vengono raschiate automaticamente da Sphinx-gallery. Se ciò non è desiderato, esiste anche un account Matplotlib Google/Gmail con nome utente mplgithub che è stato utilizzato per configurare l'account github ma può essere utilizzato per altri scopi, come l'hosting di documenti Google o video di Youtube. Puoi incorporare un'animazione Matplotlib nei documenti salvando prima l'animazione come filmato utilizzando matplotlib.animation.Animation.save(), quindi caricandola sul canale Youtube di Matplotlib e inserendo la stringa di incorporamento fornita da YouTube come:

.. raw:: html

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

Un esempio di comando di salvataggio per generare un filmato è simile al seguente

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

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

Contatta Michael Droettboom per la password di accesso per caricare i video di YouTube di Google Docs sull'account mplgithub.

Generazione di diagrammi di ereditarietà #

I diagrammi di ereditarietà delle classi possono essere generati con la direttiva del diagramma di ereditarietà Sphinx.

Esempio:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2
Diagramma di ereditarietà di matplotlib.patches, matplotlib.lines, matplotlib.text