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

Aperta
  • Qualcosa non va?
#598 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
ci-cd, documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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
Lingua principale
Python
Stelle
214
Fork
68
Merge medio
51m
PR unite (30g)
6

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Backblaze/b2-sdk-python

Tutte le issue di Backblaze/b2-sdk-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.