B2 SDK docs: convert embedded TODO directives into tracked documentation issues

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

Los mantenedores suelen responder en 1 día

@ffumero2003 ya está trabajando en esto.

Desde el 9/9/2026.

  • #603 de @ffumero2003 — abierto

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
22/100
Tipo de issue
Documentación
Claridad
Necesita aclaración
Estado de actividad
Estancado
Stack tecnológico
python
Área
documentation

Línea de trabajo

Start with the todo:: and TODO:: directives in doc/source/index.rst, advanced.rst and doc/source/api, and with how doc/source/conf.py gates them behind B2_SPHINX_TODO. Classify each entry as obsolete, documentation work, API design or deferred. The work is already claimed by open pull request #603, so check that thread before starting. Done means every TODO is removed or linked to a focused issue.

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

Descripción

Description

Several Sphinx pages contain embedded todo directives for missing explanations, raw-simulator coverage, list consistency, exception documentation, progress documentation, and an advanced-API design concern. doc/source/conf.py only includes them when B2_SPHINX_TODO is enabled. In the normal published build they are invisible, and they carry no owner, priority, acceptance criteria, or discussion history.

Steps to reproduce

1. Search doc/source/index.rst, advanced.rst, and doc/source/api for `todo::` or `TODO::`.
2. Build the documentation without B2_SPHINX_TODO enabled.
3. Observe that the pending work is absent from the normal output and is not linked to tracked issues.

Expected behavior

Review each TODO and classify it as obsolete, documentation work, API design work, or intentionally deferred. Remove obsolete entries, create focused issues for actionable work, and replace any retained source TODO with a link to its issue and a reason it remains useful in the source.

Actual behavior

Maintenance work is hidden inside source files and can remain unnoticed indefinitely. Some TODOs describe user-facing documentation gaps, while another describes a possible API change; keeping them together without tracking also obscures different owners and compatibility risks.

Environment

  • Python version: Not applicable
  • b2sdk version: master at f3ab7b71
  • OS: Not applicable
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.