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

Abierto
  • ¿Algo no está bien?
#598 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
30/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
python
Área
ci-cd, documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
Python
Estrellas
214
Forks
68
Merge medio
51 min
PR fusionados (30 d)
6

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Backblaze/b2-sdk-python

Todos los issues de Backblaze/b2-sdk-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.