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

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

Maintainer antworten meist innerhalb von 1 Tag

@ffumero2003 arbeitet bereits daran.

Seit 09.9.2026.

  • #603 von @ffumero2003 — offen

Bewertung

Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Anfängerfreundlichkeit
22/100
Issue-Typ
Dokumentation
Klarheit
Muss geklärt werden
Aktivitätsstatus
Veraltet
Tech-Stack
python
Bereich
documentation

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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