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

Offen
  • Stimmt etwas nicht?
#598 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
30/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Ruhig
Tech-Stack
python
Bereich
ci-cd, documentation

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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
Vorherrschende Sprache
Python
Sterne
214
Forks
68
Ø Merge
51 Min.
Gemergte PRs (30 T.)
6

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus Backblaze/b2-sdk-python

Alle Issues in Backblaze/b2-sdk-python

Ähnliche Issues

Weitere Issues zu Python

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.