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

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

I maintainer di solito rispondono entro 1 giorno

@ffumero2003 ci sta già lavorando.

Dal 9/9/2026.

  • #603 di @ffumero2003 — aperta

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
22/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Ferma
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

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.

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

Descrizione

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
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.