MEP12: Melhorar Galeria e Exemplos #

Estado #

Progresso

Alterações iniciais adicionadas em 1.3. A conversão da galeria está em andamento. 29 de setembro de 2015 - O último pylab_examplesonde pylabé importado foi convertido para usar matplotlib.pyplote numpy.

Filiais e solicitações pull #

nº 1623, nº 1924, nº 2181

PR #2474 demonstra um único exemplo sendo limpo e movido para a seção apropriada.

Resumo #

A reorganização da galeria de plotagem matplotlib simplificaria bastante a navegação na galeria. Além disso, os exemplos devem ser limpos e simplificados para maior clareza.

Descrição detalhada #

A galeria matplotlib foi recentemente configurada para dividir os exemplos em seções. Conforme discutido naquele PR [ 1 ] , as seções de exemplo atuais ( api, pylab_examples) não são muito úteis para os usuários: Novas seções na galeria ajudariam os usuários a encontrar exemplos relevantes.

Essas seções também orientariam uma limpeza dos exemplos: Inicialmente, todos os exemplos atuais permaneceriam e seriam listados em seus diretórios atuais. Com o tempo, esses exemplos podem ser limpos e movidos para uma das novas seções.

Esse processo permite que os usuários identifiquem facilmente os exemplos que precisam ser limpos; ou seja, qualquer coisa nos diretórios apie pylab_examples .

Implementação #

Crie novas seções de galeria. [Feito]
Limpe os exemplos e mova-os para as novas seções da galeria (ao longo de muitos PRs e com a ajuda de muitos usuários/desenvolvedores). [Em andamento]

Seções da galeria #

A nomenclatura das seções é crítica e orientará o esforço de limpeza. As seções atuais são:

Linhas, barras e marcadores (dados 1D mais ou menos)
Formas e coleções
Gráficos estatísticos
Imagens, contornos e campos
Gráficos circulares e polares: coisas redondas
Cor
Texto, rótulos e anotações
Carrapatos e espinhos
Subtramas, eixos e figuras
Parcelas especiais (por exemplo, sankey, radar, tornado)
Showcase (plots com ajustes para torná-los de qualidade de publicação)
seções separadas para caixas de ferramentas (já existe: 'mplot3d', 'axes_grid', 'unidades', 'widgets')

Esses nomes certamente estão em debate. À medida que essas seções crescem, devemos reavaliá-las e dividi-las conforme necessário.

Diretrizes de limpeza #

Os exemplos atuais nas seções apie pylab_examplesda galeria permaneceriam nesses diretórios até serem limpos. Após a limpeza, eles seriam movidos para uma das novas seções da galeria descritas acima. A "limpeza" deve envolver:

sphinx-gallery docstrings : um título e uma descrição do exemplo formatado da seguinte forma, na parte superior do exemplo:

"""
===============================
Colormaps alter your perception
===============================

Here I plot the function

.. math:: f(x, y) = \sin(x) + \cos(y)

with different colormaps. Look at how colormaps alter your perception!
"""

Limpezas PEP8 (executar flake8 , ou um verificador semelhante, é altamente recomendado)
O código comentado deve ser removido.
Substitua os usos da pylabinterface por pyplot(+ numpy, etc.). Ver c25ef1e
Remova a linha shebang, por exemplo:

#!/usr/bin/env python
Use importações consistentes. Em particular:

importar numpy como np

importar matplotlib.pyplot como plt

Evite importar funções específicas desses módulos (por exemplo )from numpy import sin
Cada exemplo deve se concentrar em um recurso específico (excluindo showcaseexemplos, que mostrarão gráficos mais "polidos"). Ajustes não relacionados a esse recurso devem ser removidos. Consulte f7b2217 , e57b5fc e 1458aa8

O uso de pylabdeve ser demonstrado/discutido em uma página de ajuda dedicada, em vez dos exemplos da galeria.

Observação: ao mover um exemplo existente, você deve procurar referências a esse exemplo. Por exemplo, a documentação da API para axes.pye pyplot.pypode usar esses exemplos para gerar gráficos. Use sua ferramenta de pesquisa favorita (por exemplo, grep, ack, grin , pss ) para pesquisar o pacote matplotlib. Veja 2dc9a46 e aa6b410

Sugestões adicionais #

Forneça links (nos dois sentidos) entre exemplos e documentos da API para os métodos/objetos usados. (edição nº 2222 )
Use plt.subplots(observe "s" à direita) de preferência sobre plt.subplot.
Renomeie o exemplo para esclarecer seu propósito. Por exemplo, a demonstração mais básica de imshowpode ser imshow_demo.py, e uma demonstração de diferentes configurações de interpolação seria imshow_demo_interpolation.py( not imshow_demo2.py ).
Divida os exemplos que tentam fazer demais. Consulte 5099675 e fc2ab07
Exclua os exemplos que não apresentam nada de novo.
Alguns exemplos exercitam recursos esotéricos para testes de unidade. Esses ajustes devem ser movidos para fora da galeria para um exemplo no unitdiretório localizado no diretório raiz do pacote.
Adicione títulos de enredo para esclarecer a intenção do exemplo. Veja bd2b13c

Compatibilidade com versões anteriores #

O site para cada versão do Matplotlib é facilmente acessível, portanto, os usuários que desejam consultar exemplos antigos ainda podem fazê-lo.

Alternativas #

Etiquetas #

Marcar exemplos também ajudará os usuários a pesquisar na galeria de exemplos. Embora as tags sejam uma grande vitória para usuários com objetivos específicos, a galeria de plotagem continuará sendo o ponto de entrada para esses exemplos, e as seções podem realmente ajudar os usuários a navegar na galeria. Assim, as tags são complementares a essa reorganização.