Pular para o conteúdo principal

Python · tools/gerar_documentacao

Fonte: tools/gerar_documentacao.

FunçãoLinhasResumoReferências diretas
current_commit30–39Resolve o permalink do fonte sem exigir rede ou autenticação.0
tree_digest42–47Indexa arquivos por caminho e hash para comparação determinística.2
check_outputs50–62Compara a saída recém-gerada com os artefatos locais, sem modificá-los.3
clean_managed_output65–74Remove apenas a árvore marcada como gerada e os dois JSON conhecidos.2
build77–82Extrai o inventário e escreve páginas MDX e dados JSON públicos.4
main85–115CLI: 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"