docs(mkdocs): API navegable por temas + navegación y UX enriquecidas#267
Open
complexluise wants to merge 2 commits into
Open
docs(mkdocs): API navegable por temas + navegación y UX enriquecidas#267complexluise wants to merge 2 commits into
complexluise wants to merge 2 commits into
Conversation
…a API Varias líneas de docstring empezaban con '#54:', '#126', '#141', '#159'. Python-Markdown (mkdocstrings) no exige espacio tras '#', así que las tomaba como headings H1: ensuciaban el cuerpo y volcaban docstrings enteros en la tabla de contenidos de reference/python-api. Se antepone 'Ref ' para preservar la trazabilidad del issue sin generar un heading. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Estructural - Divide la referencia de API monolítica en 6 páginas por tema bajo una sección expandible del navbar (Corpus y persistencia, Fuentes, Forrajeo, Redes, Análisis, Exportadores) con una portada de overview (grid cards). Preserva la superficie pública curada en vez de auto-exponer el árbol de módulos. La URL /reference/python-api/ se conserva (era una página, ahora es el index de la sección). mkdocstrings - Íconos de tipo (clase/método/atributo) en headings y TOC, índice de miembros por objeto (summary: Methods/Attributes), crossrefs clicables en las firmas, y Args/Returns como tabla. Navegación y UX (mkdocs-material) - Breadcrumbs (navigation.path), footer anterior/siguiente, prune y barra de progreso; tooltips (abreviaturas + preview de símbolos); anotaciones en bloques de código; diagramas Mermaid (showcase en ARCHITECTURE, con el ASCII anotado debajo). - vigila src/ para que `mkdocs serve` recargue con cambios de docstrings. Enlaces entrantes a la API actualizados a la nueva ruta (guías, tutorial). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Qué
Hace la documentación más navegable, sobre todo la referencia de API de Python (antes un muro de ~35 objetos en una sola página con un TOC gigante). Incluye el fix del TOC roto que originó todo.
Cambios
fix(docs)— docstrings que empezaban con#NNN(#54,#126,#141,#159) los tomaba Python-Markdown como headings H1 y volcaba docstrings enteros en el TOC. Se anteponeRefpara preservar la trazabilidad sin generar heading.docs(mkdocs)— la mejora:/reference/python-api/se conserva.summary), crossrefs clicables en firmas, Args/Returns como tabla.ARCHITECTURE, con el ASCII anotado debajo).watch: srcpara quemkdocs serverecargue con cambios de docstrings.Decisiones marcadas para review
mike(versionado) y social cards — cambian deploy/CI y (social) rompen build local en Windows.git-revision-date-localized(fechas por página) — se quitó por overkill: dependencia extra + cambio de CI para poco valor.Verificación
Build CI-equivalente (
mkdocs build --clean) limpio; las 6 páginas renderizan, sin fugas en el TOC. Enlaces entrantes a la API actualizados.🤖 Generated with Claude Code