Pular para o conteúdo principal

Python · tools/documentacao/render

Fonte: tools/documentacao/render.

FunçãoLinhasResumoReferências diretas
fence41–45Cria code fence MDX seguro para código que contenha crases.0
protect48–58Escapa sintaxe MDX acidental em prosa, sem tocar em código Markdown.2
quote61–63Transforma comentário em blockquote Markdown seguro para MDX.0
plain66–68Reduz texto Markdown a uma descrição curta para metadados.0
code_language71–74Mapeia extensão de arquivo para linguagem de realce Prism.0
Renderer.__init__78–93Inicializa índices de referências, símbolos e auditoria do renderizador.0
Renderer.macro_target95–101Resolve apelido curto para a macro canônica definida no cabeçalho público.0
Renderer.macro_category103–128Classifica macro por família semântica para navegação e índice.0
Renderer.slug130–144Gera rota estável por tipo/módulo, reunindo apelidos de macro.0
Renderer.link146–148Cria link Markdown para a página de um símbolo.0
Renderer.gh150–153Monta permalink GitHub para arquivo e linha no commit do build.0
Renderer.gh_link155–157Cria link Markdown para fonte/linha no GitHub.0
Renderer.page159–169Registra página MDX com frontmatter determinístico e metadados.0
Renderer.category171–174Registra categoria de sidebar Docusaurus.0
Renderer.contract176–201Resolve contrato editorial por nome, padrão, apelido ou função relacionada.0
Renderer.names_for203–205Retorna nome canônico e apelidos usados na busca de evidências.0
Renderer.direct_refs207–217Reúne referências diretas do símbolo e de seus apelidos sem duplicatas.0
Renderer.source_snippet219–227Recorta linhas de contexto e resolve fonte real de heredoc virtual.0
Renderer.faq229–243Monta a seção de perguntas frequentes de uma página. Cada item traz uma pergunta, parágrafos de resposta e, opcionalmente, um trecho de código real (fonte, test0
Renderer.external_conditions245–248Condições reais de plataforma, sem a guarda de inclusão do cabeçalho.0
Renderer.usage_snippet250–260Recorta o primeiro uso real do símbolo nos testes, com linguagem e linha.0
Renderer.symbol_recipe262–277Comando real de build/teste para exercitar o símbolo na stack do projeto.0
Renderer.integration_checklist279–313Checklist de integração derivado do tipo, do módulo e dos guards do símbolo.0
Renderer.symbol_faq315–439Perguntas frequentes específicas de uma página de símbolo.0
Renderer.category_faq441–480FAQ de uma família de macros, montado com nomes e expansões reais.0
Renderer.module_faq482–517FAQ de um módulo da biblioteca, com receita de build e contrato de retorno.0
Renderer.render_refs519–560Renderiza arquivos, linhas, contextos e trechos de uso em testes.0
Renderer.indirect_refs562–578Mostra chamadores e testes deles como evidência indireta explícita.0
Renderer.modes_for580–595Calcula quais modos do harness alcançam o símbolo pelo grafo de chamadas.0
Renderer.runner_mode_lines597–604Localiza invocações literais de um modo no runner da biblioteca.0
Renderer.render_modes606–619Renderiza modos de integração/falha fatal ligados ao símbolo.0
Renderer.nearby_directives621–629Diretivas vizinhas que afetam atributos/diagnósticos, não só o corpo.0
Renderer.portability631–682Renderiza guards, diretivas, marcadores e ressalvas de compilador/OS.0
Renderer.render_symbol684–794Monta a página completa de um símbolo com contrato, fonte, testes e portabilidade.0
Renderer.render_indexes796–935Gera índices de referência por família de macro e módulo de biblioteca.0
Renderer.render_tests937–1053Gera índice de suítes, casos, harness e modos de integração.0
Renderer.suite_faq1055–1091FAQ de uma suíte de casos dourados, com contagens e modos reais.0
Renderer.case_faq1093–1133FAQ de um caso dourado: execução, arquivos e resultado esperado.0
Renderer.mode_faq1135–1161FAQ de um modo de integração/falha fatal do harness.0
Renderer.render_case1163–1196Renderiza um caso dourado/negativo/aviso com todos os seus arquivos.0
Renderer.render_harness1198–1233Lista funções C de teste e scripts runners com links de fonte.0
Renderer.internal_faq1235–1262FAQ de um arquivo interno (transpilador, harness, runner ou script).0
Renderer.example_faq1264–1293FAQ de um exemplo executável, com compilação e resultado esperado.0
Renderer.render_internals1295–1339Agrupa funções internas por linguagem e arquivo.0
Renderer.render_examples1341–1375Publica exemplos versionados e suas saídas douradas.0
Renderer.related_symbols1377–1392Símbolos públicos realmente citados no texto, em ordem de ocorrência.0
Renderer.document_extra1394–1412Acrescenta a um documento importado os símbolos citados e o FAQ editorial.0
Renderer.import_markdown1414–1426Importa documento original ajustando título, links e sintaxe MDX.0
Renderer.rewrite_links1428–1451Reescreve links relativos para páginas importadas ou permalinks GitHub.0
Renderer.rewrite_links.replace1436–1450Resolve um link Markdown individual contra o mapa de documentos/fontes.0
Renderer.escape_mdx1453–1472Escapa prosa linha a linha sem modificar blocos de código fenced.0
Renderer.render_project1474–1515Importa especificação, decisões, relatórios, README e cobertura versionada.0
Renderer.render_build1517–1564Gera página viva de Makefile, workflows e comandos de build.0
Renderer.write1566–1618Renderiza todas as páginas, guias e JSONs e escreve a árvore gerenciada.0

Perguntas frequentes​

Perguntas frequentes sobre tools/documentacao/render e as 54 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 fence(text: str, language: str = "text") -> str:
def protect(text: str) -> str:
def quote(text: str) -> str:
def plain(text: str) -> str:
def code_language(path: str) -> str:
def __init__(self, inv: Inventory, contracts: dict, repo_url: str, commit: str):

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/documentacao/render

As funções internas têm teste próprio?​

1 das 54 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 fence?​

Cria code fence MDX seguro para código que contenha crases.

def fence(text: str, language: str = "text") -> str:
"""Cria code fence MDX seguro para código que contenha crases."""
runs = re.findall(r"`+", text)
ticks = "`" * max(3, max((len(r) + 1 for r in runs), default=3))
return f"{ticks}{language}\n{text.rstrip()}\n{ticks}\n"