python / python/cpython

Update annotation parameters for objects in documentation

Aberta
#129,667 0 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

docs
Linguagem predominante
Python
Estrelas
77.2k
Forks
35.9k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

Working on PR #129607 noticed that one parameter was missing in http.server.HTTPServer documentation, so I decided to send a separate PR to update the documentation and at the same time check some more entities in the stdlib.

And I started to finding a lot of such cases and wanted to automate it. Then I found out that sphinx already has something similar to do automatically now I offer you this as an idea. Maybe it is possible to include such a feature in sphinx or write your own script so that it checks this in CI (for example using inspect and rst parser).

It seems very important to me that the documentation is accurate in such things and doesn't become outdated

I don't think it's a good practice for contributors to change parameters in the documentation themselves (or forget about it :-).
At least we could report discrepancies between documentation and annotations from code.

I'll send PR with what I've already found.

Linked PRs
  • gh-129669

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Comece pelo parâmetro ausente na documentação de http.server.HTTPServer e revise o PR #129669. Em seguida, examine a abordagem proposta com Sphinx ou uma verificação de CI usando inspect e um parser rst. Considera-se concluído quando um caminho de implementação e o escopo para detectar discrepâncias entre anotações e documentação tiverem sido acordados.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
documentation, tooling
Tipo de issue
Documentação
Dificuldade
5/5
Tempo estimado
Mais de uma semana
Status de atividade
Estagnada
Clareza
Precisa de esclarecimento
Facilidade para iniciantes
25/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.