Renderer.render_indexes
Gerada por tools/gerar_documentacao.py. Definição: tools/documentacao/render.py:796.
Gera índices de referência por família de macro e módulo de biblioteca.
Tipo: função Python · Visibilidade: pública · Arquivo: tools/documentacao/render.py.
Assinatura e expansão
def render_indexes(self) -> None:
Parâmetros formais: self.
Como funciona
Gera índices de referência por família de macro e módulo de biblioteca.
Implementação completa · 140 linhas
def render_indexes(self) -> None:
"""Gera índices de referência por família de macro e módulo de biblioteca."""
counts = Counter(s.kind for s in self.inv.symbols.values())
self.category("referencia", "Referência da API", 20)
self.category("referencia/linguagem", "Palavras-chave e macros", 10)
self.category("referencia/funcoes", "Funções da biblioteca", 20)
body = ["# Referência viva\n\n",
f"Inventário extraído de **{len(self.inv.symbols)} símbolos**: "
f"{counts['macro']} macros, {counts['função C']} funções C, "
f"{counts['função Python']} funções Python e {counts['função Shell']} funções Shell. "
"Apelidos curtos/prefixados são reunidos na mesma página de macro.\n\n",
":::note[O que é automático]\nNomes, assinaturas, expansões, guards, chamadores, arquivos de teste, "
"linhas, casos dourados e modos fatais vêm do repositório a cada build. Contratos editoriais são "
"complementados por comentários/docstrings; um símbolo novo aparece mesmo antes de ganhar prosa especial.\n:::\n\n",
"Use a busca local para procurar qualquer nome, incluindo apelidos. "
"O [inventário JSON](pathname:///api/inventario.json) é a saída determinística para auditoria.\n\n",
"## Macros e palavras-chave\n\n"]
grouped = defaultdict(list)
for macro in self.canonical_macros:
grouped[self.macro_category(macro)].append(macro)
for category, symbols in sorted(grouped.items()):
label = CAT_LABELS[category]
folder = f"referencia/linguagem/{category}"
self.category(folder, label, 10 + len(body))
rows = ["# " + label + "\n\n", "| Nome(s) | Contrato | Usos diretos em testes | Portabilidade | Fonte |\n",
"|---|---|---:|---|---|\n"]
for symbol in sorted(symbols, key=lambda s: s.name):
contract = self.contract(symbol)
summary = protect(plain(contract.get("resumo") or symbol.comment or symbol.body or "Ver definição")[:130]).replace("|", "\\|")
refs = self.direct_refs(symbol)
files = len({r.path for r in refs})
port = "condicional" if symbol.conditions or PLATFORM.search(symbol.body) else "compartilhada"
names = " / ".join(symbol.aliases)
rows.append(f"| {self.link(symbol)}{chr(32) + chr(96) + names + chr(96) if names else ''} | {summary} | {files} arquivo(s) | {port} | {self.gh_link(symbol.path, symbol.line, label='fonte')} |\n")
rows.append(self.category_faq(category, label, symbols))
self.page(folder + "/index", label, "".join(rows), label="Visão geral", position=0)
body.append(f"- [{label}](/{folder}/) — {len(symbols)} página(s)\n")
body.append("\n## Funções C da biblioteca\n\n")
modules = defaultdict(list)
for function in self.functions:
if function.path.startswith(("include/", "src/")):
modules[function.module].append(function)
for module, symbols in sorted(modules.items()):
label = MODULE_LABELS.get(module, module)
folder = f"referencia/funcoes/{module}"
self.category(folder, label, 10)
rows = ["# " + label + "\n\n", "| Função | Visibilidade | Resumo | Arquivos de teste | Fonte |\n", "|---|---|---|---:|---|\n"]
for symbol in sorted(symbols, key=lambda s: s.name):
summary = protect(plain(self.contract(symbol).get("resumo") or symbol.comment or "Ver corpo")[:150]).replace("|", "\\|")
files = len({r.path for r in self.direct_refs(symbol)})
rows.append(f"| {self.link(symbol)} | {symbol.visibility} | {summary} | {files} | {self.gh_link(symbol.path, symbol.line, label='fonte')} |\n")
rows.append(self.module_faq(module, label, symbols))
self.page(folder + "/index", label, "".join(rows), label="Visão geral", position=0)
body.append(f"- [{label}](/{folder}/) — {len(symbols)} função(ões)\n")
body.append("\n## Funções internas\n\nVeja [o inventário interno](/internos/) para transpilador, testes, runners e scripts Python.\n")
lang_rows = ["# Palavras-chave e macros\n\n"]
for category, symbols in sorted(grouped.items()):
lang_rows.append(f"- [{CAT_LABELS[category]}](/referencia/linguagem/{category}/) — {len(symbols)} página(s)\n")
lang_rows.append(self.faq(
"Perguntas frequentes sobre as palavras-chave e macros da linguagem.",
[
{"q": "Por onde começo a explorar a linguagem?",
"a": ["Pelas famílias que você usa primeiro: programa/declarações, controle de fluxo, "
"operadores e entrada/saída. Cada família tem uma visão geral com tabela e FAQ, e "
"cada nome tem sua própria página com expansão e usos em testes."],
"code": "#include <basicgol.h>\n\nINICIO\n ESCREVAL(\"primeiro programa\");\nFIM",
"lang": "c"},
{"q": "Um nome curto e um `BG_*` podem ser usados juntos?",
"a": ["Podem, porque são textualmente o mesmo nome. Misturar estilos no mesmo arquivo "
"prejudica a leitura; escolha um por arquivo. As páginas reúnem as referências dos "
"dois nomes."]},
{"q": "Quantas macros existem hoje?",
"a": [f"Há **{counts['macro']} macros** inventariadas, agrupadas em "
f"**{len(grouped)} famílias**. O número inclui macros internas de configuração e "
"de teste, que aparecem em famílias próprias."]},
{"q": "Por que algumas macros não têm exemplo?",
"a": ["Exemplos editoriais vêm de `contratos.json`. Sem contrato, a página mostra o corpo "
"literal da macro e os usos reais; o gerador não inventa uma chamada."]},
{"q": "Onde está a diferença entre M0 e M1?",
"a": ["No perfil de cada construtor: macros redutíveis funcionam no M0; construções que "
"exigem reordenar tokens só existem no M1. Veja [Arquitetura](/guias/arquitetura)."]},
]))
self.page("referencia/linguagem/index", "Palavras-chave e macros", "".join(lang_rows), label="Visão geral", position=0)
func_rows = ["# Funções da biblioteca\n\n"]
for module, symbols in sorted(modules.items()):
func_rows.append(f"- [{MODULE_LABELS.get(module, module)}](/referencia/funcoes/{module}/) — {len(symbols)} função(ões)\n")
func_rows.append(self.faq(
"Perguntas frequentes sobre as funções C da biblioteca padrão.",
[
{"q": "Preciso ligar a biblioteca para usar essas funções?",
"a": ["Sim. As funções `bg_*` são compiladas em `build/libbasicgol.a`; o cabeçalho "
"declara os protótipos. Sem o archive (ou os fontes de `src/biblioteca/`) a "
"ligação falha com `undefined reference`."],
"code": "make biblioteca\ncc -std=c11 -I include programa.c build/libbasicgol.a -lm -o programa",
"lang": "bash"},
{"q": "Como essas funções reportam erro?",
"a": ["A maioria devolve `LOGICO`: `false` significa entrada inválida, truncamento ou "
"falha de E/S, e o destino não é alterado (strings ficam vazias quando há espaço "
"para o NUL). Operações fatais são exceções documentadas, como divisor zero em "
"`DIVIDE`."]},
{"q": "Qual é a diferença entre a função `bg_*` e a macro em português?",
"a": ["A macro é a interface didática; a função é o código compilado. Quando os nomes "
"coincidem semanticamente, a página da macro mostra a função associada e ambas as "
"páginas apontam para o mesmo contrato."]},
{"q": "As funções são thread-safe?",
"a": ["Texto, caractere, console e matemática não mantêm estado global. A exceção é o "
"gerador pseudoaleatório de `utilidades`, que compartilha estado de processo e não "
"é criptográfico nem thread-safe."]},
{"q": "Como os módulos são testados?",
"a": ["Por uma suíte unitária própria, além dos casos dourados da linguagem."],
"code": "make test-biblioteca\nmake test", "lang": "bash"},
]))
self.page("referencia/funcoes/index", "Funções da biblioteca", "".join(func_rows), label="Visão geral", position=0)
body.append(self.faq(
"Perguntas frequentes sobre a referência gerada, suas contagens e seus limites.",
[
{"q": "O que existe nesta referência?",
"a": [f"**{len(self.inv.symbols)} símbolos** inventariados: {counts['macro']} macros, "
f"{counts['função C']} funções C, {counts['função Python']} funções Python e "
f"{counts['função Shell']} funções Shell. Macros curtas e prefixadas ficam na "
"mesma página; funções públicas são agrupadas por módulo."]},
{"q": "Como procuro um nome ou um apelido?",
"a": ["Use a busca local do site (atalho de teclado na barra) ou o inventário JSON. "
"A busca indexa também os aliases, que aparecem no título das páginas de macro."],
"code": "python3 -c \"import json; print(json.load(open('website/static/api/inventario.json'))['counts'])\"",
"lang": "bash"},
{"q": "Por que uma página não tem exemplo de uso?",
"a": ["Exemplos editoriais vêm de `tools/documentacao/contratos.json`. Sem contrato, o "
"gerador mostra a expansão, o corpo, os protótipos e os usos reais dos testes; "
"ele não inventa uma chamada que o código não demonstra."]},
{"q": "Uma contagem alta aqui significa boa cobertura?",
"a": ["Não. As contagens são estáticas e incluem menções, não execuções. O total "
"impresso por `make test` é dinâmico. Compare apenas métricas iguais e leia "
"[como ler as evidências](/guias/como-ler)."]},
{"q": "Como um símbolo novo aparece no site?",
"a": ["Basta defini-lo em `include/`, `src/`, `tools/` ou `tests/` e rodar o gerador. "
"Não existe lista manual de páginas; o build falha se a saída ficar desatualizada."],
"code": "python3 tools/gerar_documentacao.py --strict\npython3 tools/gerar_documentacao.py --check", "lang": "bash"},
]))
self.page("referencia/index", "Referência viva", "".join(body), label="Visão geral", position=0)
Nomes internos referenciados: plain, protect.
Como este símbolo aparece nos testes
Nenhuma referência direta a este nome foi encontrada nos arquivos de teste. Isso pode ser esperado para guardas de inclusão, configuração ou código exercitado indiretamente; não é uma afirmação de cobertura zero.
Compiladores, padrão C e sistema operacional
Nenhum ramo condicional externo foi detectado para este símbolo. A implementação é compartilhada no fonte; isso não certifica compiladores ou sistemas não executados.
- Script Python: usa a biblioteca padrão e pathlib/subprocess quando aplicável; caminhos não devem depender do separador de um único OS.
A matriz histórica distingue executado, compilado, avaliado e não testado. Consulte a matriz, os compiladores e os logs atuais dos workflows antes de chamar um alvo de suportado.
Perguntas frequentes
Perguntas reunidas a partir da definição, do contrato editorial e dos testes de Renderer.render_indexes. As respostas repetem apenas o que o repositório mostra; quando não há evidência, isso é dito.
Em uma frase, o que Renderer.render_indexes faz?
Gera índices de referência por família de macro e módulo de biblioteca.
Qual é a assinatura e o tipo de retorno de Renderer.render_indexes?
Assinatura extraída de tools/documentacao/render.py; visibilidade pública.
def render_indexes(self) -> None:
Como chamar Renderer.render_indexes corretamente?
Nenhum exemplo editorial nem chamada direta em teste foi localizada. A forma de uso é a assinatura acima; os chamadores aparecem na seção de evidência indireta quando existem.
def render_indexes(self) -> None:
Por que não há teste direto para Renderer.render_indexes?
A busca estática não encontrou o identificador nos arquivos de teste. Isso é esperado para guardas de inclusão, configuração de build e nomes alcançados apenas por chamadores internos. O JSON de cobertura registra a lacuna em vez de convertê-la em aprovação.
Renderer.render_indexes depende de compilador, padrão C ou sistema operacional?
Renderer.render_indexes é uma função Python: requer Python 3.10+ e biblioteca padrão, sem compilador C.
O que acontece em caso de falha ou uso inválido?
Não há ressalva editorial específica para este nome. O comportamento em falha é o do corpo/expansão mostrado acima; não invente validação que o fonte não faz.