B2 SDK docs: execute or signature-check documentation examples in CI

Ouverte
  • Quelque chose ne va pas ?
#598 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
30/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Calme
Stack technique
python
Domaine
ci-cd, documentation

Piste de recherche

Start from docs/quick_start.rst and the Sphinx configuration (conf.py) that builds it, then inspect the CI documentation job that runs the non-interactive Sphinx build. Read the unit-test command using --doctest-modules to see why module doctests miss .rst code blocks. Done means the docs job fails on the invalid EncryptionSettings, EncryptionKey, and file_infos examples while deterministic RawSimulator examples execute and credential-dependent signatures are checked without B2 calls.

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

Description

Description

The Sphinx build validates document structure and cross-references, but examples in ordinary code-block directives are rendered as text and are not executed. The unit-test command uses --doctest-modules, which checks Python-module docstrings rather than .rst code blocks, and the Sphinx configuration does not enable sphinx.ext.doctest. This is why invalid names and keyword arguments in the Quick Start guide can pass CI.

Steps to reproduce

1. Observe the existing invalid `EncryptionSettings`, `EncryptionKey(id=...)`, or `file_infos=` examples in quick_start.rst.
2. Run the current non-interactive documentation build.
3. Observe that Sphinx can render the page without executing those calls.

Expected behavior

Define two validation levels. Self-contained examples should execute against RawSimulator or another deterministic fixture. Credential-dependent examples should be extracted or represented in a form that checks syntax, imports, object construction, and method signatures without contacting B2. The documentation job should fail with a clear file and example location when validation fails.

Actual behavior

Documentation currently builds successfully while containing Python examples that fail immediately when copied into an application. This creates a false signal: CI proves that pages render, not that the documented SDK calls remain valid.

Environment

  • Python version: Any supported version
  • b2sdk version: master at f3ab7b71
  • OS: Any
Langage dominant
Python
Étoiles
214
Forks
68
Merge moyen
51 min
PR mergées (30 j)
6

Préparer son environnement

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.

Autres issues de Backblaze/b2-sdk-python

Toutes les issues de Backblaze/b2-sdk-python

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

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