vprusso/toqito

docs: add missing Raises: sections to function docstrings

Fermée

#1 888 ouverte le 25 juil. 2026

Voir sur GitHubGuide contributeur
 (1 commentaire) (0 réaction) (0 personne assignée)Python (154 forks)github user discovery
documentationgood first issue

Métriques du dépôt

Stars
 (277 étoiles)
Métriques de merge PR
 (Métriques PR en attente)

Description

Many functions raise ValueError/TypeError on bad input but do not document it in a Raises: docstring section. Adding these sections makes the API self-documenting and surfaces the conditions in the rendered docs.

What to do

For a function that raises but has no Raises: section, add one listing each exception and the condition that triggers it, in the Google style used elsewhere in the codebase:

    Raises:
        ValueError: If `dim` does not evenly divide the input.

Good targets (pick a few per PR):

  • toqito/channel_ops/kraus_to_choi.py
  • toqito/channel_props/channel_dim.py
  • toqito/channels/amplitude_damping.py, bitflip.py, phase_damping.py, ldot_channel.py
  • toqito/matrices/cyclic_permutation.py

List each raise and its condition with:

git grep -nE "raise (Value|Type)Error" toqito/<file>

Verifying

uv sync --group docs
cd docs && uv run mkdocs build

Confirm the new Raises: section renders on the function's docs page.

Guide contributeur

Direction de recherche
Utilisez `git grep nE "raise (Value|Type)Error" toqito/` pour trouver les fonctions qui lèvent des exceptions mais n'ont pas de section Raises. Ajoutez une section Raises de style Google à ces docstrings et reconstruisez la documentation avec `uv sync group docs && cd docs && uv run mkdocs build` pour vérifier le rendu.
Stack technique
python
Domaine
documentation
Type d'issue
Documentation
DifficultéDifficulté estimée pour un nouveau contributeur, de 1 pour un très petit changement à 5 pour un travail expert.
2
Temps estiméFourchette de temps approximative pour investiguer, implémenter, tester et préparer une pull request.
1-3 heures
Statut d'activitéDisponibilité apparente de l'issue : fraîche, active, ancienne, bloquée ou en attente d'un mainteneur.
Active
ClartéClarté avec laquelle l'issue explique le changement attendu, les critères d'acceptation et la prochaine étape.
Claire
Prérequis
GitPython
Accessibilité débutantScore de 1 à 100 estimant l'accessibilité de cette issue pour un premier contributeur.
80