MEP10: Consistência docstring #

Estado #

Progresso

Este ainda é um esforço contínuo

matplotlib tem muita inconsistência entre docstrings. Isso não apenas torna os documentos mais difíceis de ler, mas também é mais difícil para os contribuidores, porque eles não sabem quais especificações seguir. Deve haver uma convenção de docstring clara que seja seguida de forma consistente.

A organização da documentação da API é difícil de seguir. Algumas páginas, como pyplot e axes, são enormes e difíceis de navegar. Em vez disso, deve haver tabelas de resumo curtas com links para documentação detalhada. Além disso, algumas das próprias docstrings são bastante longas e contêm informações redundantes.

Construir a documentação leva muito tempo e usa um make.py script em vez de um Makefile.

Descrição detalhada #

Há uma série de novas ferramentas e convenções disponíveis desde que o matplotlib começou a usar o Sphinx que torna a vida mais fácil. A seguir está uma lista de alterações propostas para docstrings, a maioria das quais envolve esses novos recursos.

Formato de docstring Numpy #

Numpy docstring format : Este formato divide a docstring em seções claras, cada uma com diferentes regras de análise que tornam a docstring fácil de ler tanto como texto bruto quanto como HTML. Poderíamos considerar alternativas ou inventar nossas próprias, mas esta é uma escolha forte, pois é bem usada e compreendida na comunidade Numpy/Scipy.

Referências cruzadas #

A maioria das docstrings no matplotlib usa "funções" explícitas ao vincular a outros itens, por exemplo: :func:`myfunction`. A partir do Sphinx 0.4, existe um "default_role" que pode ser definido como "obj", que será vinculado polimorficamente a um objeto Python de qualquer tipo. Isso permite escrever `myfunction`em vez disso. Isso torna as docstrings muito mais fáceis de ler e editar como texto bruto. Além disso, o Sphinx permite definir um módulo atual, para que links como `~matplotlib.axes.Axes.set_xlim` possam ser escritos como `~axes.Axes.set_xlim`.

Substituindo assinaturas #

Muitos métodos em matplotlib usam a sintaxe *argse **kwargspara manipular dinamicamente os argumentos de palavra-chave que são aceitos pela função ou para delegar para outra função. Isso, no entanto, muitas vezes não é útil como assinatura na documentação. Por esse motivo, muitos métodos matplotlib incluem algo como:

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

Isso não pode ser analisado pelo Sphinx e é bastante detalhado em texto bruto. A partir do Sphinx 1.1, se o autodoc_docstring_signaturevalor de configuração for definido como True, o Sphinx extrairá uma assinatura de substituição da primeira linha da docstring, permitindo o seguinte:

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

A assinatura explícita substituirá a assinatura real do Python na documentação gerada.

Vinculando em vez de duplicar #

Muitas das docstrings incluem longas listas de palavras-chave aceitas interpolando coisas na docstring no tempo de carregamento. Isso torna as docstrings muito longas. Além disso, como essas tabelas são as mesmas em muitos docstrings, ele insere muitas informações redundantes nos documentos - particularmente um problema na versão impressa.

Essas tabelas devem ser movidas para docstrings em funções cujo único objetivo é ajudar. As docstrings que se referem a essas tabelas devem ser vinculadas a elas, em vez de incluí-las literalmente.

extensão de resumo automático #

A extensão de resumo automático do Sphinx deve ser usada para gerar tabelas de resumo, com links para páginas separadas de documentação. Algumas classes que possuem muitos métodos (por exemplo Axes) devem ser documentadas com um método por página, enquanto classes menores devem ter todos os seus métodos juntos.

Exemplos com links para documentação relevante #

Os exemplos, embora úteis para ilustrar como usar um recurso, não são vinculados às docstrings relevantes. Isso pode ser resolvido adicionando docstrings de nível de módulo aos exemplos e, em seguida, incluindo essa docstring no conteúdo analisado na página de exemplo. Essas docstrings podem facilmente incluir referências a qualquer outra parte da documentação.

Documentação usando help() versus um navegador #

O uso da marcação Sphinx na fonte permite documentos de boa aparência em seu navegador, mas a marcação também faz com que o texto bruto retornado usando help() pareça terrível. Um dos objetivos de melhorar as docstrings deve ser fazer com que ambos os métodos de acesso aos documentos tenham uma boa aparência.

Implementação #

As extensões numpydoc devem ser ativadas para matplotlib. Há uma questão importante sobre se eles devem ser incluídos na árvore de origem do matplotlib ou usados como uma dependência. A instalação do Numpy não é suficiente para obter as extensões numpydoc - é um procedimento de instalação separado. Em qualquer caso, na medida em que exigem personalização para nossas necessidades, devemos nos esforçar para enviar essas alterações upstream e não fork.
Percorra manualmente todas as docstrings e atualize-as para o novo formato e convenções. A atualização das referências cruzadas (de `:func:`myfunc`para `func`) pode ser semi-automatizada. Isso é muito trabalho ocupado e talvez esse trabalho deva ser dividido por módulo para que nenhum desenvolvedor seja sobrecarregado por ele.
Reorganize os documentos da API usando autosummary e sphinx-autogen. Esperançosamente, isso deve ter um impacto mínimo na documentação narrativa.
Modifique o gerador de página de exemplo ( gen_rst.py) para que ele extraia o módulo docstring do exemplo e o inclua em uma parte não literal da página de exemplo.
Use sphinx-quickstartpara gerar um novo estilo Sphinx Makefile. Os seguintes recursos no atual make.pyterão que ser abordados de alguma outra maneira:
- Cópia de algum conteúdo estático
- Especificando uma compilação "pequena" (somente arquivos PNG de baixa resolução para exemplos)

As etapas 1, 2 e 3 são interdependentes. 4 e 5 podem ser feitos independentemente, embora 5 tenha alguma dependência de 3.

Compatibilidade com versões anteriores #

Como isso envolve principalmente docstrings, deve haver um impacto mínimo na compatibilidade com versões anteriores.

Alternativas #

Nenhum ainda discutido.