Escrever documentação

Primeiros passos

Estrutura geral do arquivo

Toda a documentação é construída a partir do doc/. O doc/ diretório contém arquivos de configuração para arquivos Sphinx e reStructuredText ( ReST ; .rst) que são renderizados para páginas de documentação.

A documentação é criada de três maneiras. Primeiro, a documentação da API ( doc/api) é criada pelo Sphinx a partir das docstrings das classes na biblioteca Matplotlib. Com exceção de doc/api/api_changes/, os .rstarquivos em doc/apisão criados quando a documentação é construída. Veja Escrevendo docstrings abaixo.

Em segundo lugar, o conteúdo de doc/plot_types, doc/gallerye doc/tutorialsé gerado pela Sphinx Gallery a partir de arquivos python em plot_types/, examples/e tutorials/. Essas fontes consistem em scripts python que possuem documentação ReST incorporada em seus comentários. Veja exemplos de escrita e tutoriais abaixo.

Terceiro, o Matplotlib tem documentos narrativos escritos em ReST em subdiretórios de doc/users/. Se você quiser adicionar uma nova documentação adequada a um .rstarquivo em vez de uma galeria ou exemplo de tutorial, escolha um subdiretório apropriado para colocá-lo e adicione o arquivo ao sumário do index.rstsubdiretório. Consulte Escrevendo páginas ReST abaixo.

Observação

Não edite diretamente os .rstarquivos em doc/plot_types, doc/gallery, doc/tutorialse doc/api (exceto doc/api/api_changes/). O Sphinx regenera os arquivos nesses diretórios ao construir a documentação.

Configurando a compilação do documento

A documentação para Matplotlib é gerada a partir de reStructuredText ( ReST ) usando a ferramenta de geração de documentação Sphinx .

Para construir a documentação, você precisará configurar o Matplotlib para desenvolvimento . Observe em particular as dependências adicionais necessárias para construir a documentação.

Construindo os documentos

As fontes de documentação são encontradas no doc/diretório no tronco. O arquivo de configuração do Sphinx é doc/conf.py. Ele controla quais diretórios o Sphinx analisa, como os documentos são construídos e como as extensões são usadas. Para construir a documentação no formato html, entre no cd doc/e execute:

make html

Outras invocações úteis incluem

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

# Build pdf docs.
make latexpdf

A SPHINXOPTSvariável é definida por padrão para criar os documentos completos, mas saia com status de saída 1 se houver avisos. Para desativá-lo, use-W --keep-going

make SPHINXOPTS= html

Você pode usar a Ovariável para definir opções adicionais:

• make O=-j4 htmlexecuta uma construção paralela com 4 processos.

• make O=-Dplot_formats=png:100 htmlsalva figuras em baixa resolução.

• make O=-Dplot_gallery=0 htmlpula a construção da galeria.

Várias opções podem ser combinadas, por exemplo .make O='-j4 -Dplot_gallery=0' html

No Windows, defina as opções como variáveis ​​de ambiente, por exemplo:

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

Mostrando documentos construídos localmente

Os documentos construídos estão disponíveis na pasta build/html. Um atalho para abri-los em seu navegador padrão é:

make show

Escrevendo páginas ReST

A maior parte da documentação está nas docstrings de classes e métodos individuais, em .rstarquivos explícitos ou em exemplos e tutoriais. Todos eles usam a sintaxe ReST e são processados ​​pelo Sphinx .

O Sphinx reStructuredText Primer é uma boa introdução ao uso do ReST. Informações mais completas estão disponíveis na documentação de referência do reStructuredText .

Esta seção contém informações e convenções adicionais sobre como o ReST é usado na documentação do Matplotlib.

Convenções de formatação e estilo

É útil buscar consistência na documentação do Matplotlib. Aqui estão algumas convenções de formatação e estilo que são usadas.

Formatação da seção

Para tudo, exceto capítulos de nível superior, use para títulos de seção, por exemplo, em vez deUpper lowerPossible hangupsPossible Hangups

Nosso objetivo é seguir as recomendações da documentação do Python e da documentação do Sphinx reStructuredText para caracteres de marcação de seção, ou seja:

• #com overline, para peças. Isso é reservado para o título principal em index.rst. Todas as outras páginas devem começar com "capítulo" ou inferior.

• *com overline, para capítulos

• =, para seções

• -, para subseções

• ^, para subseções

• ", para parágrafos

Isso pode ainda não ser aplicado de forma consistente em documentos existentes.

Argumentos da função

Argumentos de função e palavras-chave dentro de docstrings devem ser referidos usando a *emphasis*função. Isso manterá a documentação do Matplotlib consistente com a documentação do Python:

Here is a description of *argument*

Não use o :`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.

nem o ``literal``papel:

Do not describe ``argument`` like this.

Referindo-se a outros documentos e seções

Sphinx permite referências internas entre documentos.

Os documentos podem ser vinculados à :doc:diretiva:

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`

renderizará como:

Veja a instalação

Veja o tutorial Guia de início rápido

Veja o exemplo de Gráfico Simples

As seções também podem receber nomes de referência. Por exemplo, no link de instalação :

.. _clean-install:

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

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

e consulte-o usando a sintaxe de referência padrão:

See :ref:`clean-install`

dará o seguinte link: Como remover completamente o Matplotlib

Para maximizar a consistência interna na rotulagem e referências de seção, use rótulos descritivos separados por hífen para referências de seção. Lembre-se de que o conteúdo pode ser reorganizado posteriormente, portanto, evite nomes de nível superior em referências como userou devel ou faqa menos que seja necessário, porque, por exemplo, o FAQ "o que é um back-end?" poderia mais tarde se tornar parte do guia do usuário, então o rótulo:

.. _what-is-a-backend:

é melhor que:

.. _faq-backend:

Além disso, como os sublinhados são amplamente usados ​​pelo próprio Sphinx, use hífens para separar as palavras.

Referindo-se a outro código

Para vincular a outros métodos, classes ou módulos no Matplotlib, você pode usar back ticks, por exemplo:

`matplotlib.collections.LineCollection`

gera um link como este: matplotlib.collections.LineCollection.

Observação: usamos a configuração sphinx para que você não precise usar qualificadores como , e semelhantes.default_role = 'obj':class::func::meth:

Freqüentemente, você não deseja mostrar o pacote completo e o nome do módulo. Contanto que o alvo não seja ambíguo, você pode simplesmente deixá-lo de fora:

`.LineCollection`

e o link ainda funciona: LineCollection.

Se houver vários elementos de código com o mesmo nome (por exemplo plot(), é um método em várias classes), você terá que estender a definição:

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

Eles aparecerão como pyplot.plotou Axes.plot. Para ainda mostrar apenas o último segmento, você pode adicionar um til como prefixo:

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

renderizará como plotou plot.

Outros pacotes também podem ser vinculados via intersphinx :

`numpy.mean`

retornará este link: numpy.mean. Isso funciona para Python, Numpy, Scipy e Pandas (a lista completa está em doc/conf.py). Se a vinculação externa falhar, você pode verificar a lista completa de objetos referenciados com os seguintes 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'

Incluindo figuras e arquivos

Os arquivos de imagem podem ser incluídos diretamente nas páginas com a image::diretiva. por exemplo, tutorials/intermediate/constrainedlayout_guide.pyexibe algumas imagens estáticas:

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

Os arquivos podem ser incluídos literalmente. Por exemplo, o LICENSEarquivo está incluído no contrato de licença usando

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

O diretório de exemplos é copiado doc/gallerypor sphinx-gallery, então gráficos do diretório de exemplos podem ser incluídos usando

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

Observe que o script python que gera o gráfico é referido, em vez de qualquer gráfico criado. A Sphinx-gallery fornecerá a referência correta quando a documentação for construída.

Escrevendo docstrings

A maior parte da documentação da API é escrita em docstrings. Estes são blocos de comentários no código-fonte que explicam como o código funciona.

Observação

Algumas partes da documentação ainda não estão em conformidade com o estilo de documentação atual. Em caso de dúvida, siga as regras fornecidas aqui e não o que você pode ver no código-fonte. Solicitações de atualização de docstrings para o estilo atual são muito bem-vindas.

Todas as docstrings novas ou editadas devem estar em conformidade com o guia numpydoc docstring . Grande parte da sintaxe ReST discutida acima ( Escrevendo páginas ReST ) pode ser usada para links e referências. Esses docstrings eventualmente preenchem o doc/apidiretório e formam a documentação de referência para a biblioteca.

Exemplo de cadeia de documentos

Um exemplo de docstring se parece com:

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 a hlinesdocumentação para saber como isso é renderizado.

O site do Sphinx também contém muita documentação sobre a marcação ReST e o trabalho com o Sphinx em geral.

Convenções de formatação

As convenções básicas de docstring são abordadas no guia numpydoc docstring e na documentação do Sphinx . Algumas convenções de formatação específicas do Matplotlib a serem lembradas:

Posições de cotação

As aspas para docstrings de linha única estão na mesma linha (pydocstyle D200):

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

As aspas para docstrings de várias linhas estão em linhas separadas (pydocstyle D213):

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

[...]
"""

Argumentos da função

Argumentos de função e palavras-chave dentro de docstrings devem ser referidos usando a *emphasis*função. Isso manterá a documentação do Matplotlib consistente com a documentação do Python:

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

Não use o ou a função:`default role```literal``

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

Citações para strings

O Matplotlib não tem uma convenção para usar aspas simples ou duplas. Há uma mistura de ambos no código atual.

Use aspas simples ou duplas ao fornecer valores de string, por exemplo

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

No ``'extra'`` literal quotes.

O uso de citações literais extras ao redor do texto é desencorajado. Embora eles melhorem ligeiramente os documentos renderizados, eles são complicados de digitar e difíceis de ler em documentos de texto simples.

Descrições do tipo de parâmetro

O principal objetivo das descrições de tipo de parâmetro é ser legível e compreensível por humanos. Se os tipos possíveis forem muito complexos, use uma simplificação para a descrição do tipo e explique o tipo com mais precisão no texto.

Geralmente, as convenções do guia de docstring numpydoc se aplicam. As regras a seguir as expandem onde as convenções numpydoc não são específicas.

Use floatpara um tipo que pode ser qualquer número.

Use para descrever uma posição 2D. Os parênteses devem ser incluídos para tornar a tupla mais óbvia.(float, float)

Use array-likepara sequências numéricas homogêneas, que normalmente podem ser um numpy.array. A dimensionalidade pode ser especificada usando 2D, 3D, n-dimensional. Se você precisar de variáveis ​​que indiquem os tamanhos das dimensões, use letras maiúsculas entre colchetes ( ). Ao referir-se a eles no texto, eles são mais fáceis de ler e nenhuma formatação especial é necessária. Use em vez de para tipos de retorno se o objeto retornado for de fato uma matriz numpy.(M, N) array-likearrayarray-like

floaté o dtype padrão implícito para tipos de array. Para outros dtypes, use .array-like of int

Alguns usos possíveis:

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

Sequências homogêneas não numéricas são descritas como listas, por exemplo:

list of str
list of `.Artist`

Tipos de referência

Geralmente, as regras de referência a outro código se aplicam. Mais especificamente:

Use referências completas `~matplotlib.colors.Normalize`com um til de abreviação em tipos de parâmetro. Embora o nome completo ajude o leitor de docstrings de texto simples, o HTML não precisa mostrar o nome completo ao vincular a ele. Portanto, o ~-shortening o mantém mais legível.

Use links abreviados `.Normalize`no texto.

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

Valores padrão

Ao contrário do guia numpydoc, os parâmetros não precisam ser marcados como opcionais se tiverem um padrão simples:

• usar quando possível.{name} : {type}, default: {val}

• use e descreva o padrão no texto se não puder ser explicado suficientemente da maneira recomendada.{name} : {type}, optional

O valor padrão deve fornecer informações semânticas direcionadas a um leitor humano. Em casos simples, ele reafirma o valor na assinatura da função. Se aplicável, as unidades devem ser adicionadas.

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

Se Nenhum for usado apenas como um valor sentinela para "parâmetro não especificado", não o documente como padrão. Dependendo do contexto, forneça o padrão atual ou marque o parâmetro como opcional se não especificar não tiver nenhum efeito específico.

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 alsoseções

O Sphinx liga automaticamente os elementos de código nos blocos de definição das seções. Não há necessidade de usar backticks lá:See also

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

Envolvendo listas de parâmetros

Listas de parâmetros longos devem ser agrupadas usando um \for continuation e começando na nova linha sem qualquer recuo (sem recuo porque pydoc irá analisar a docstring e remover a continuação da linha para que o recuo resulte em muitos espaços em branco dentro da linha):

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

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

    ...
    """

Como alternativa, você pode descrever os valores de parâmetro válidos em uma seção dedicada da docstring.

rcParams

rcParams pode ser referenciado com a :rc:função personalizada: :rc:`foo`yields , que é um link para a descrição do arquivo.rcParams["foo"] = 'default'matplotlibrc

Setters e getters

As propriedades do artista são implementadas usando os métodos setter e getter (porque o Matplotlib é anterior ao propertydecorador do Python). Por convenção, esses setters e getters são nomeados set_PROPERTYNAMEe get_PROPERTYNAME; a lista de propriedades assim definidas em um artista e seus valores podem ser listados pelas funções setpe getp.

O bloco Parâmetros dos métodos de definição de propriedade é analisado para documentar os valores aceitos, por exemplo, a docstring de Line2D.set_linestylecomeça com

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

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

que resulta na seguinte linha na saída de plt.setp(line)ou :plt.setp(line, "linestyle")

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

Em alguns casos raros (principalmente, setters que aceitam uma única tupla e uma tupla não compactada), os valores aceitos não podem ser documentados dessa maneira; nesse caso, eles podem ser documentados como um bloco, por exemplo, 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.
    """

Observe que a entrelinha ..torna o bloco um comentário reST, ocultando-o dos documentos renderizados... ACCEPTS:

Argumentos de palavras-chave

Observação

As informações nesta seção estão sendo discutidas ativamente pela equipe de desenvolvimento, portanto, use a interpolação docstring somente se necessário. Esta seção foi mantida por enquanto porque esta interpolação faz parte da documentação existente.

Como o Matplotlib usa muitos pass-through kwargs, por exemplo, em todas as funções que criam uma linha ( plot, semilogx, semilogyetc.), pode ser difícil para o novo usuário saber quais kwargssão suportados. Matplotlib usa um esquema de interpolação docstring para dar suporte à documentação de todas as funções que usam um arquivo **kwargs. Os requisitos são:

1. único ponto de configuração para que as alterações nas propriedades não exijam várias edições de docstring.

2. o mais automatizado possível para que, à medida que as propriedades mudam, os documentos sejam atualizados automaticamente.

O @_docstring.interpddecorador implementa isso. Qualquer função que aceita Line2Dpassagem kwargs, por exemplo, matplotlib.axes.Axes.plot, pode listar um resumo das Line2Dpropriedades, como 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
    """

A %(Line2D:kwdoc)sintaxe interpdpesquisa uma Artistsubclasse chamada Line2De chama artist.kwdocessa classe. artist.kwdoc examina a subclasse e resume suas propriedades como uma substring, que é interpolada na docstring.

Observe que esse esquema não funciona para decorar um Artist's __init__, pois a subclasse e suas propriedades ainda não estão definidas nesse ponto. Em vez disso, @_docstring.interpdpode ser usado para decorar a própria classe - nesse ponto, kwdocpode listar as propriedades e interpolá-las em arquivos __init__.__doc__.

Herdando docstrings

Se uma subclasse substitui um método, mas não altera a semântica, podemos reutilizar a docstring pai para o método da classe filha. O Python faz isso automaticamente, se o método da subclasse não tiver uma docstring.

Use um comentário simples para denotar a intenção de reutilizar a docstring pai. Dessa forma, não criamos acidentalmente uma docstring no futuro:# docstring inherited

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

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

Adicionando números

Como acima (consulte Incluindo figuras e arquivos ), as figuras na galeria de exemplos podem ser referenciadas com uma diretiva apontando para o script python que criou a figura. Por exemplo, a docstring faz referência ao arquivo :.. plot::legendexamples/text_labels_and_annotations/legend.py

"""
...

Examples
--------

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

Observe que examples/text_labels_and_annotations/legend.pyfoi mapeado para gallery/text_labels_and_annotations/legend.py, um redirecionamento que pode ser corrigido em uma futura reorganização dos documentos.

Os gráficos também podem ser colocados diretamente dentro de docstrings. Os detalhes estão em matplotlib.sphinxext.plot_directive . Um pequeno exemplo é:

"""
...

Examples
--------

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

Uma vantagem desse estilo sobre a referência a um script de exemplo é que o código também aparecerá em docstrings interativas.

Escrevendo exemplos e tutoriais

Exemplos e tutoriais são scripts python executados pela Sphinx Gallery para criar uma galeria de imagens nos diretórios /doc/gallerye /doc/tutorialsrespectivamente. Para excluir um exemplo de ter um gráfico gerado, insira "sgskip" em algum lugar no nome do arquivo.

O formato desses arquivos é relativamente direto. Os blocos de comentários formatados corretamente são tratados como texto ReST , o código é exibido e as figuras são colocadas na página construída.

Por exemplo, o exemplo Simple Plot é gerado a partir de /examples/lines_bars_and_markers/simple_plot.py, que se parece com:

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

O primeiro bloco de comentário é tratado como texto ReST . Os outros blocos de comentários são renderizados como comentários em Simple Plot .

Os tutoriais são feitos exatamente com o mesmo mecanismo, exceto que são mais longos e geralmente têm mais de um bloco de comentários (ou seja, guia de início rápido ). O primeiro bloco de comentários pode ser o mesmo do exemplo acima. Os blocos subsequentes de texto ReST são delimitados por uma linha 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)))

Desta forma, o texto, o código e as figuras são produzidos no estilo "notebook".

Referências para sphinx-galeria

As funções Matplotlib exibidas devem ser listadas em uma advertência na parte inferior da seguinte forma

###############################################################################
#
# .. admonition:: References
#
#    The use of the following functions, methods, classes and modules is shown
#    in this example:
#
#    - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
#    - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`

Isso permite que a sphinx-gallery coloque uma entrada para o exemplo na mini-galeria das funções mencionadas. Se uma função é ou não mencionada aqui deve ser decidida dependendo se um link de mini-galeria ajuda a ilustrar essa função; por exemplo, mencione matplotlib.pyplot.subplotsapenas em exemplos que tratam da criação de subtramas, não em todos os exemplos que o usam.

As funções que existem em pyplotAxes ou Figure devem mencionar ambas as referências, independentemente de qual delas é usada no código de exemplo. A pyplot referência deve ser sempre a segunda a ser mencionada; veja o exemplo acima.

Ordem dos exemplos na galeria

A ordem das seções dos Tutoriais e dos Exemplos , bem como a ordem dos exemplos dentro de cada seção são determinadas em um processo de duas etapas dentro do /doc/sphinxext/gallery_order.py:

• Ordem explícita : Este arquivo contém uma lista de pastas para a ordem da seção e uma lista de exemplos para a ordem da subseção. A ordem dos itens mostrados nas páginas do documento é a ordem em que esses itens aparecem nessas listas.

• Ordem implícita : Se uma pasta ou exemplo não estiver nessas listas, ele será anexado após os itens explicitamente ordenados e todos esses itens adicionais serão ordenados por nome de caminho (para as seções) ou por nome de arquivo (para as subseções).

Como consequência, se você quiser que seu exemplo apareça em uma determinada posição na galeria, estenda essas listas com seu exemplo. Caso nenhuma ordem explícita seja desejada ou necessária, certifique-se de nomear seu exemplo de forma consistente, ou seja, use a função principal ou assunto do exemplo como primeira palavra no nome do arquivo; por exemplo, um exemplo de imagem deve ter um nome semelhante a imshow_mynewexample.py.

Diversos

Documentação de mudança

Às vezes é desejável mover ou consolidar a documentação. Sem nenhuma ação, isso levará a links que ficarão inativos (404) ou apontarão para versões antigas da documentação. É preferível substituir a página antiga por uma atualização html que redireciona imediatamente o visualizador para a nova página. Então, por exemplo, passamos /doc/topic/old_info.rstpara /doc/topic/new_info.rst. Nós removemos /doc/topic/old_info.rste /doc/topic/new_info.rstinserimos uma redirect-fromdiretiva que diz ao sphinx para ainda criar o arquivo antigo com a atualização/redirecionamento html nele (provavelmente perto do topo do arquivo para torná-lo perceptível)

.. redirect-from:: /topic/old_info

Nos documentos construídos, isso produzirá um arquivo html /build/html/topic/old_info.htmlque foi atualizado para new_info.html. Se os dois arquivos estiverem em subdiretórios diferentes:

.. redirect-from:: /old_topic/old_info2

produzirá um arquivo html /build/html/old_topic/old_info2.htmlcom uma atualização (relativa) para ../topic/new_info.html.

Use o caminho completo para esta diretiva, relativo à raiz do documento em https://matplotlib.org/stable/. Portanto /old_topic/old_info2, seria encontrado pelos usuários em http://matplotlib.org/stable/old_topic/old_info2. Para maior clareza, não use links relativos.

Adicionando animações

As animações são raspadas automaticamente pelo Sphinx-gallery. Se isso não for desejado, há também uma conta Matplotlib do Google/Gmail com nome de usuário mplgithub que foi usado para configurar a conta do github, mas pode ser usado para outros fins, como hospedar documentos do Google ou vídeos do Youtube. Você pode incorporar uma animação Matplotlib nos documentos salvando primeiro a animação como um filme usando matplotlib.animation.Animation.save()e, em seguida, enviando para o canal do YouTube do Matplotlib e inserindo a string de incorporação que o youtube fornece como:

.. raw:: html

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

Um exemplo de comando salvar para gerar um filme é semelhante a este

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

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

Entre em contato com Michael Droettboom para obter a senha de login para enviar vídeos do youtube do google docs para a conta mplgithub.

Gerando diagramas de herança

Os diagramas de herança de classe podem ser gerados com a diretiva Sphinx de diagrama de herança .

Exemplo:

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
   :parts: 2

Barra de navegação e estilo

O Matplotlib tem alguns subprojetos que compartilham a mesma barra de navegação e estilo, portanto, eles são centralizados como um tema de esfinge em mpl_sphinx_theme . As alterações no estilo ou na barra superior devem ser feitas para se propagar em todos os subprojetos.