python / python/cpython

Update annotation parameters for objects in documentation

Ouverte
#129,667 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

docs
Langage dominant
Python
Étoiles
77.2k
Forks
36k
Métriques de merge des PR
Métriques de PR en attente

Description

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

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par le paramètre manquant dans la documentation de http.server.HTTPServer et examinez la PR #129669. Étudiez ensuite l’approche proposée avec Sphinx ou une vérification CI utilisant inspect et un analyseur rst. Le travail est terminé lorsqu’une voie d’implémentation et le périmètre de détection des divergences entre les annotations et la documentation sont convenus.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
documentation, tooling
Type d'issue
Documentation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
À clarifier
Accessibilité débutants
25/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.