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

Aberta
  • Algo errado?
#601 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@ffumero2003 já está trabalhando nisso.

Desde 9/9/2026.

  • #603 de @ffumero2003 — aberto

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
22/100
Tipo de issue
Documentação
Clareza
Precisa de esclarecimento
Status de atividade
Estagnada
Stack de tecnologia
python
Domínio
documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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
Linguagem predominante
Python
Estrelas
214
Forks
68
Merge médio
51min
PRs com merge (30d)
6

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de Backblaze/b2-sdk-python

Todas as issues de Backblaze/b2-sdk-python

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.