Guia de estilo de documentação #

Este guia contém as melhores práticas para a linguagem e formatação da documentação do Matplotlib.

Veja também

Para obter mais informações sobre como contribuir, consulte a seção Escrevendo documentação .

Linguagem expositiva #

Para redação explicativa, as diretrizes a seguir são para uso de linguagem clara e concisa.

Terminologia #

Existem vários termos-chave no Matplotlib que são padrões de confiabilidade e consistência na documentação. Eles não são intercambiáveis.

Prazo	Descrição	Correto	Incorreta
`Figure`	Espaço de trabalho Matplotlib para programação.	Para objetos Matplotlib : Figura, "A Figura é o espaço de trabalho para o visual. Referindo-se à classe : `Figure`, "Métodos dentro do `Figure` fornecem os recursos visuais." Linguagem geral : figura, "Michelle Kwan é uma famosa patinadora artística."	"A figura é o espaço de trabalho para visuais." "Os métodos na figura fornecem os recursos visuais." "O `Figure` Four leglock é um movimento de luta livre."
`Axes`	Subtramas dentro da Figura. Contém elementos de plotagem e é responsável por plotar e configurar detalhes adicionais.	Para objetos Matplotlib : Axes, "Um Axes é uma subtrama dentro da Figura." Referindo-se à classe : `Axes`, "Cada um `Axes`é específico para uma Figura." Linguagem geral : machados, "Tanto madeireiros quanto lenhadores usam machados para cortar madeira." OU "Não há nomes padrão para as coordenadas nos três eixos." (plural de eixo)	"Os métodos axes transformam os dados." "Cada um `Axes`é específico para uma Figura." "Os músicos no palco chamam suas guitarras de Axes." "O ponto onde os eixos se encontram é a origem do sistema de coordenadas."
`Artist`	Ampla variedade de objetos Matplotlib que exibem recursos visuais.	Para objetos Matplotlib : Artista, "Artistas exibem recursos visuais e são os elementos visíveis ao renderizar uma Figura." Referindo-se à classe : `Artist`, "Cada um `Artist` tem seus respectivos métodos e funções." Linguagem geral : artista, "O artista no museu é da França."	"Configurar o artista da legenda com seu respectivo método." "Existe um `Artist` para esse visual no gráfico." "Alguns artistas ficaram famosos apenas por acidente."
`Axis`	Objeto unidimensional legível por humanos de marcas de referência contendo marcações, rótulos de marcações, lombadas e arestas.	Para objetos Matplotlib : Axis, "O Eixo para o gráfico de barras é um Artista separado." (plural, objetos do eixo) Referindo-se à classe : `Axis`, "O `Axis` contém os respectivos objetos XAxis e YAxis." Linguagem geral : eixo, "A rotação em torno de um eixo fixo é um caso especial de movimento rotacional."	"Plote o gráfico no eixo." "Cada Eixo geralmente recebe o nome da coordenada que é medida ao longo dele." "Em alguns contextos de computação gráfica, a ordenada `Axis`pode ser orientada para baixo."
Programação Orientada a Objetos (OOP) Explícita	Abordagem explícita de programação em Matplotlib.	Explícito explícito OOP	Orientado a Objeto estilo OO
Implícito, `pyplot`	Abordagem implícita de programação em Matplotlib com `pyplot`módulo.	Implícito implícito `pyplot`	como MATLAB Pyplot interface do pyplot

Gramática #

Assunto #

Use frases imperativas de segunda pessoa para instruções direcionadas especificando uma ação. Os pronomes da segunda pessoa são para contextos individuais específicos e referência possessiva.

Correto	Incorreta
Instale o Matplotlib a partir do diretório de origem usando o `pip` programa instalador do Python. Dependendo do seu sistema operacional, você pode precisar de suporte adicional.	Você pode instalar o Matplotlib a partir do diretório de origem. Você pode encontrar suporte adicional se estiver tendo problemas com a instalação.

Tenso #

Use o tempo presente simples para explicações. Evite o tempo futuro e outros verbos modais ou auxiliares quando possível.

Correto	Incorreta
As ideias fundamentais por trás do Matplotlib para visualização envolvem pegar dados e transformá-los por meio de funções e métodos.	O Matplotlib pegará os dados e os transformará por meio de funções e métodos. Eles podem gerar muitos tipos de recursos visuais. Esses serão os fundamentos para usar o Matplotlib.

Voz #

Escreva em frases ativas. A voz passiva é melhor para situações ou condições relacionadas a avisos de alerta.

Correto	Incorreta
A função `plot`gera o gráfico.	O gráfico é gerado pela `plot`função.
Uma mensagem de erro é retornada pela função se não houver argumentos.	Você verá uma mensagem de erro da função se não houver argumentos.

Estrutura da frase #

Escreva com frases curtas usando a ordem Sujeito-Verbo-Objeto regularmente. Limite as conjunções coordenativas nas frases. Evite referências a pronomes e frases conjuntivas subordinadas.

Correto	Incorreta
O `pyplot`módulo no Matplotlib é uma coleção de funções. Essas funções criam, gerenciam e manipulam a Figura atual e a área de plotagem.	O `pyplot`módulo no Matplotlib é uma coleção de funções que criam, gerenciam e manipulam a figura atual e a área de plotagem.
A `plot`função plota os dados nos respectivos eixos. Os Eixos correspondem à respectiva Figura.	A `plot`função plota dados dentro de seus respectivos eixos para sua respectiva figura.
A abordagem implícita é um atalho conveniente para gerar gráficos simples.	Os usuários que desejam ter atalhos convenientes para gerar gráficos usam a abordagem implícita.

Formatando #

As diretrizes a seguir especificam como incorporar código e usar a formatação apropriada para a documentação do Matplotlib.

Código #

Matplotlib é uma biblioteca Python e segue os mesmos padrões de documentação.

Comentários #

Exemplos de código Python têm comentários antes ou na mesma linha.

Correto	Incorreta
# Data years = [2006, 2007, 2008]	years = [2006, 2007, 2008] # Data
years = [2006, 2007, 2008] # Data	years = [2006, 2007, 2008] # Data

Saídas #

Ao gerar visuais com Matplotlib usando .pyarquivos em exemplos, exiba o visual com matplotlib.pyplot.showpara exibir o visual. Mantenha a documentação livre de linhas de saída do Python.

Correto	Incorreta
plt.plot([1, 2, 3], [1, 2, 3]) plt.show()	plt.plot([1, 2, 3], [1, 2, 3])
fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3]) fig.show()	fig, ax = plt.subplots() ax.plot([1, 2, 3], [1, 2, 3])

reStructuredText #

Matplotlib usa marcação reStructuredText para documentação. O Sphinx ajuda a transformar esses documentos em formatos apropriados para acessibilidade e visibilidade.

Listas #

Listas com marcadores são para itens que não requerem sequenciamento. As listas numeradas são exclusivamente para a realização de ações em uma determinada ordem.

Correto	Incorreta
O exemplo usa três gráficos.	O exemplo usa três gráficos.
Bar Linha Torta	Bar Linha Torta
Essas quatro etapas ajudam a começar a usar o Matplotlib.	As etapas a seguir são importantes para começar a usar o Matplotlib.
Importe a biblioteca Matplotlib. Importe os módulos necessários. Defina e atribua dados para trabalhar. Transforme dados com métodos e funções.	Importe a biblioteca Matplotlib. Importe os módulos necessários. Defina e atribua dados para trabalhar. Transforme dados com métodos e funções.

Mesas #

Use tabelas ASCII com padrões reStructuredText na organização do conteúdo. As tabelas Markdown e a diretiva csv-table não são aceitas.

Correto

Incorreta

Correto	Incorreta
OK	Não está tudo bem

| Correct | Incorrect |
| ------- | --------- |
| OK      | Not OK    |

+----------+----------+
| Correct  | Incorrect|
+==========+==========+
| OK       | Not OK   |
+----------+----------+

.. csv-table::
   :header: "correct", "incorrect"
   :widths: 10, 10

   "OK   ", "Not OK"

===========  ===========
  Correct     Incorrect
===========  ===========
OK           Not OK
===========  ===========

Recursos adicionais #

Este guia de estilo não é um padrão abrangente. Para obter uma referência mais completa sobre como contribuir com a documentação, consulte os links abaixo. Esses recursos contêm práticas recomendadas comuns para escrever documentação.