Python · tools/gerar_documentacao
Fonte: tools/gerar_documentacao.
| Função | Linhas | Resumo | Referências diretas |
|---|---|---|---|
current_commit | 30–39 | Resolve o permalink do fonte sem exigir rede ou autenticação. | 0 |
tree_digest | 42–47 | Indexa arquivos por caminho e hash para comparação determinística. | 2 |
check_outputs | 50–62 | Compara a saída recém-gerada com os artefatos locais, sem modificá-los. | 3 |
clean_managed_output | 65–74 | Remove apenas a árvore marcada como gerada e os dois JSON conhecidos. | 2 |
build | 77–82 | Extrai o inventário e escreve páginas MDX e dados JSON públicos. | 4 |
main | 85–115 | CLI: gerar, verificar determinismo e opcionalmente falhar em avisos do parser. | 9 |
Perguntas frequentes
Perguntas frequentes sobre tools/gerar_documentacao e as 6 função(ões) indexada(s) nele.
Que funções este arquivo expõe?
As funções abaixo foram extraídas do próprio arquivo. Elas são internas ao projeto: não fazem parte da API pública de basicgol.h.
def current_commit(root: Path) -> str:
def tree_digest(directory: Path) -> dict[str, str]:
def check_outputs(expected: Path, docs: Path, static_api: Path) -> list[str]:
def clean_managed_output(docs: Path, static_api: Path) -> None:
def build(root: Path, output: Path, repo_url: str, commit: str) -> dict:
def main(argv: list[str] | None = None) -> int:
Como executar este arquivo?
Depende do tipo de arquivo. A receita abaixo é a do projeto; flags e argumentos específicos estão na assinatura de cada função.
python3 tools/gerar_documentacao
As funções internas têm teste próprio?
5 das 6 funções possuem referência direta nos testes. As demais podem ser alcançadas apenas por chamadores; o JSON de cobertura registra a lacuna.
Qual é o contrato de current_commit?
Resolve o permalink do fonte sem exigir rede ou autenticação.
def current_commit(root: Path) -> str:
"""Resolve o permalink do fonte sem exigir rede ou autenticação."""
explicit = os.environ.get("DOCS_COMMIT") or os.environ.get("GITHUB_SHA")
if explicit:
return explicit
try:
return subprocess.check_output(["git", "-C", str(root), "rev-parse", "HEAD"],
text=True, stderr=subprocess.DEVNULL).strip()
except (OSError, subprocess.CalledProcessError):
return "main"