diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 69dbfe3..8fa8f23 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -34,6 +34,23 @@ visual library-centric vive en un producto separado; ADR [0040](decisiones/0040-
## 2. Vista de alto nivel
+```mermaid
+flowchart LR
+ EQ["ecuación de búsqueda
o archivo .bib"] --> SRC["Source
OpenAlex · BibTeX"]
+ SRC --> CORPUS[("CORPUS
tabla Arrow
1 fila / paper")]
+ FOR["Forrajeo
back/forward · rank = scent"] <--> CORPUS
+ PRE["Preprocessor
normalize + thesaurus"] --> CORPUS
+ CORPUS --> PROJ["Projectors
acoplamiento · co-citación
co-autoría · keyword · institución"]
+ PROJ --> NET["Networks
networkx"]
+ NET --> ANA["Análisis
métricas · centralidad
comunidades · asortatividad"]
+ NET --> EXP["Exporters
GraphML / CSV"]
+ ANA --> REP["informe de calidad"]
+ CORPUS -. persiste .-> DUCK[("DuckDBBackend
biblioteca viva · stateful")]
+ DUCK -. snapshot sellado .-> SNAP["CorpusSnapshot"]
+```
+
+*Detalle anotado del mismo flujo (con topes, procedencia y estado del ciclo):*
+
```
ecuación de búsqueda
│ (traducción + reporte de traducción, ADR 0007)
diff --git a/docs/guias/index.md b/docs/guias/index.md
index d03c83f..c754135 100644
--- a/docs/guias/index.md
+++ b/docs/guias/index.md
@@ -72,4 +72,4 @@ trabajas.
- [Tu primer mapa de investigación](../tutoriales/primer-mapa.md) — aprende desde cero, en 5 minutos
- [Quickstart](../getting-started/quickstart.md) — ciclo mínimo en 2 minutos
- [Referencia CLI](../reference/cli.md) — todos los comandos
-- [API Python](../reference/python-api.md) — como librería
+- [API Python](../reference/python-api/index.md) — como librería
diff --git a/docs/reference/python-api.md b/docs/reference/python-api.md
deleted file mode 100644
index 8d0410f..0000000
--- a/docs/reference/python-api.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-title: API de Python
----
-
-# API de Python
-
-Referencia de la **superficie pública de la librería** `bib2graph`, agrupada por
-tema. Se **autogenera desde los docstrings** del código (mkdocstrings): si cambia
-el código, cambia esta página.
-
-Para usar la herramienta desde la terminal, mira la [referencia del CLI `b2g`](cli.md).
-
-## Corpus y persistencia
-
-::: bib2graph.Corpus
-::: bib2graph.Manifest
-::: bib2graph.CorpusSnapshot
-::: bib2graph.SchemaError
-::: bib2graph.TabularBackend
-::: bib2graph.InMemoryBackend
-::: bib2graph.stores.duckdb.DuckDBStore
-::: bib2graph.backends.duckdb.DuckDBBackend
-
-## Fuentes (siembra)
-
-::: bib2graph.Source
-::: bib2graph.OpenAlexSource
-::: bib2graph.BibtexSource
-::: bib2graph.SeedResult
-
-## Forrajeo y curación
-
-::: bib2graph.Forager
-::: bib2graph.RankedCandidates
-::: bib2graph.GrowthPreview
-::: bib2graph.Preprocessor
-::: bib2graph.apply_filters
-::: bib2graph.FilterCriterion
-
-## Redes (proyección)
-
-::: bib2graph.Networks
-::: bib2graph.NetworkArtifact
-::: bib2graph.BibliographicCouplingProjector
-::: bib2graph.CoCitationProjector
-::: bib2graph.AuthorCollaborationProjector
-::: bib2graph.InstitutionCollaborationProjector
-::: bib2graph.KeywordCoOccurrenceProjector
-
-## Análisis de redes
-
-::: bib2graph.network_metrics
-::: bib2graph.centrality
-::: bib2graph.detect_communities
-::: bib2graph.assortativity
-::: bib2graph.community_composition
-::: bib2graph.cocitation_quality_report
-::: bib2graph.QualityThresholds
-
-## Exportadores
-
-::: bib2graph.GraphMLExporter
-::: bib2graph.CsvExporter
diff --git a/docs/reference/python-api/analisis.md b/docs/reference/python-api/analisis.md
new file mode 100644
index 0000000..3e45d50
--- /dev/null
+++ b/docs/reference/python-api/analisis.md
@@ -0,0 +1,17 @@
+---
+title: Análisis de redes
+---
+
+# Análisis de redes
+
+Leer las redes: métricas globales, centralidad por nodo, detección de
+comunidades, asortatividad y composición de comunidades, más el informe de
+calidad específico de la red de co-citación.
+
+::: bib2graph.network_metrics
+::: bib2graph.centrality
+::: bib2graph.detect_communities
+::: bib2graph.assortativity
+::: bib2graph.community_composition
+::: bib2graph.cocitation_quality_report
+::: bib2graph.QualityThresholds
diff --git a/docs/reference/python-api/corpus.md b/docs/reference/python-api/corpus.md
new file mode 100644
index 0000000..98df313
--- /dev/null
+++ b/docs/reference/python-api/corpus.md
@@ -0,0 +1,19 @@
+---
+title: Corpus y persistencia
+---
+
+# Corpus y persistencia
+
+El corazón del modelo de datos: el `Corpus` (una tabla canónica Arrow con
+semántica de valor), su `Manifest` de procedencia, los snapshots sellados y los
+backends que lo respaldan —puro en memoria para tests, o DuckDB para la
+biblioteca viva—.
+
+::: bib2graph.Corpus
+::: bib2graph.Manifest
+::: bib2graph.CorpusSnapshot
+::: bib2graph.SchemaError
+::: bib2graph.TabularBackend
+::: bib2graph.InMemoryBackend
+::: bib2graph.stores.duckdb.DuckDBStore
+::: bib2graph.backends.duckdb.DuckDBBackend
diff --git a/docs/reference/python-api/exportadores.md b/docs/reference/python-api/exportadores.md
new file mode 100644
index 0000000..eebbcf3
--- /dev/null
+++ b/docs/reference/python-api/exportadores.md
@@ -0,0 +1,11 @@
+---
+title: Exportadores
+---
+
+# Exportadores
+
+Llevar las redes fuera de bib2graph: `GraphMLExporter` (para Gephi, Cytoscape,
+networkx) y `CsvExporter` (nodos y aristas en tablas planas, versionables).
+
+::: bib2graph.GraphMLExporter
+::: bib2graph.CsvExporter
diff --git a/docs/reference/python-api/forrajeo.md b/docs/reference/python-api/forrajeo.md
new file mode 100644
index 0000000..5937f5d
--- /dev/null
+++ b/docs/reference/python-api/forrajeo.md
@@ -0,0 +1,17 @@
+---
+title: Forrajeo y curación
+---
+
+# Forrajeo y curación
+
+Expandir y curar el corpus: el `Forager` rankea candidatos por *information
+scent* (estructura bibliométrica determinista, sin IA), con preview de
+crecimiento antes de comprometer; el `Preprocessor` normaliza, y los filtros
+PRISMA acotan el corpus de forma trazable.
+
+::: bib2graph.Forager
+::: bib2graph.RankedCandidates
+::: bib2graph.GrowthPreview
+::: bib2graph.Preprocessor
+::: bib2graph.apply_filters
+::: bib2graph.FilterCriterion
diff --git a/docs/reference/python-api/fuentes.md b/docs/reference/python-api/fuentes.md
new file mode 100644
index 0000000..f5e6b2a
--- /dev/null
+++ b/docs/reference/python-api/fuentes.md
@@ -0,0 +1,14 @@
+---
+title: Fuentes (siembra)
+---
+
+# Fuentes (siembra)
+
+La costura de **ingesta de doble puerta**: `Source` y sus implementaciones
+siembran el corpus inicial desde una ecuación de búsqueda (OpenAlex) o un archivo
+BibTeX. Ambas puertas son primarias.
+
+::: bib2graph.Source
+::: bib2graph.OpenAlexSource
+::: bib2graph.BibtexSource
+::: bib2graph.SeedResult
diff --git a/docs/reference/python-api/index.md b/docs/reference/python-api/index.md
new file mode 100644
index 0000000..8710eb7
--- /dev/null
+++ b/docs/reference/python-api/index.md
@@ -0,0 +1,53 @@
+---
+title: API de Python
+---
+
+# API de Python
+
+Referencia de la **superficie pública de la librería** `bib2graph`, agrupada por
+tema. Se **autogenera desde los docstrings** del código (mkdocstrings): si cambia
+el código, cambia esta página.
+
+Para usar la herramienta desde la terminal, mira la [referencia del CLI `b2g`](../cli.md).
+
+!!! tip "Cómo leer esta referencia"
+ Cada objeto muestra un **índice de sus miembros** al principio (haz clic para
+ saltar) y un **ícono de tipo** —clase, método o atributo— en la tabla de
+ contenidos de la derecha. Los tipos en las firmas son **enlaces**: haz clic
+ para ir a su definición.
+
+## Mapa de la API
+
+
+
+- :material-database: **[Corpus y persistencia](corpus.md)**
+
+ El `Corpus` (tabla canónica en memoria), su `Manifest`, snapshots sellados y
+ los backends (memoria / DuckDB) que lo respaldan.
+
+- :material-seed: **[Fuentes (siembra)](fuentes.md)**
+
+ `Source` y sus implementaciones (OpenAlex, BibTeX): de una ecuación de
+ búsqueda o un `.bib` al corpus inicial.
+
+- :material-graph-outline: **[Forrajeo y curación](forrajeo.md)**
+
+ `Forager`, preview de crecimiento, preprocesamiento y filtros PRISMA para
+ expandir y curar el corpus.
+
+- :material-vector-triangle: **[Redes (proyección)](redes.md)**
+
+ `Networks` y los cinco proyectores: acoplamiento, co-citación, co-autoría,
+ colaboración institucional y co-ocurrencia de keywords.
+
+- :material-chart-scatter-plot: **[Análisis de redes](analisis.md)**
+
+ Métricas, centralidad, detección de comunidades, asortatividad y el informe
+ de calidad de co-citación.
+
+- :material-export: **[Exportadores](exportadores.md)**
+
+ `GraphMLExporter` y `CsvExporter` para llevar las redes a Gephi, Cytoscape o
+ networkx.
+
+
diff --git a/docs/reference/python-api/redes.md b/docs/reference/python-api/redes.md
new file mode 100644
index 0000000..b228b90
--- /dev/null
+++ b/docs/reference/python-api/redes.md
@@ -0,0 +1,18 @@
+---
+title: Redes (proyección)
+---
+
+# Redes (proyección)
+
+Proyectar el corpus a **redes bibliométricas**. `Networks` orquesta los cinco
+proyectores —acoplamiento bibliográfico, co-citación, co-autoría, colaboración
+institucional y co-ocurrencia de keywords—, cada uno produciendo un
+`NetworkArtifact` listo para analizar o exportar.
+
+::: bib2graph.Networks
+::: bib2graph.NetworkArtifact
+::: bib2graph.BibliographicCouplingProjector
+::: bib2graph.CoCitationProjector
+::: bib2graph.AuthorCollaborationProjector
+::: bib2graph.InstitutionCollaborationProjector
+::: bib2graph.KeywordCoOccurrenceProjector
diff --git a/docs/tutoriales/primer-mapa.md b/docs/tutoriales/primer-mapa.md
index e334053..e57a3d5 100644
--- a/docs/tutoriales/primer-mapa.md
+++ b/docs/tutoriales/primer-mapa.md
@@ -148,4 +148,4 @@ En 5 minutos:
ecuación de búsqueda, forrajeo, curación PRISMA, lectura de redes y
redacción del reporte.
- **Referencia completa:** [Todos los comandos de bib2graph](../reference/cli.md).
-- **Como librería Python:** [API Python](../reference/python-api.md).
+- **Como librería Python:** [API Python](../reference/python-api/index.md).
diff --git a/mkdocs.yml b/mkdocs.yml
index 4b108ed..4e40ca5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -23,6 +23,12 @@ edit_uri: edit/dev/docs/
docs_dir: docs
+# `mkdocs serve` solo vigila docs_dir y este archivo. La "API de Python" se
+# genera desde los docstrings de src/ (mkdocstrings); sin esto, editar el código
+# NO recarga el sitio en vivo y seguís viendo el build anterior.
+watch:
+ - src
+
# Validación de enlaces. Muchos .md fuente —los ADRs (inmutables) y los archivos
# de raíz como CONTRIBUTING/VERSIONING/AGENTS— enlazan entre sí con rutas
# relativas que son correctas en GitHub (su render principal) pero caen fuera de
@@ -61,12 +67,18 @@ theme:
- navigation.sections
- navigation.top
- navigation.instant
+ - navigation.instant.progress # barra de progreso al navegar sin recargar
- navigation.tracking
- navigation.indexes
+ - navigation.path # migas de pan (breadcrumbs) por página
+ - navigation.footer # enlaces anterior/siguiente al pie
+ - navigation.prune # solo renderiza el nav visible (perf: 38 ADRs)
- toc.follow
- search.suggest
- search.highlight
- content.code.copy
+ - content.code.annotate # anotaciones (1) dentro de bloques de código
+ - content.tooltips # tooltips en abreviaturas y preview de símbolos
- content.action.edit
plugins:
@@ -82,24 +94,35 @@ plugins:
paths: [src]
options:
docstring_style: google
+ docstring_section_style: table # Args/Returns como tabla prolija
show_root_heading: true
show_root_full_path: false
show_source: false
show_signature_annotations: true
separate_signature: true
+ signature_crossrefs: true # tipos en la firma → enlaces clicables
members_order: source
heading_level: 2
+ show_symbol_type_heading: true # ícono de tipo (clase/método/attr) en headings
+ show_symbol_type_toc: true # …y en la tabla de contenidos (escaneable)
+ summary: true # índice compacto de miembros por objeto
filters: ["!^_"]
markdown_extensions:
- admonition
+ - abbr # abreviaturas con tooltip (junto a content.tooltips)
- attr_list
- md_in_html
- tables
- toc:
permalink: true
- pymdownx.details
- - pymdownx.superfences
+ - pymdownx.superfences:
+ custom_fences:
+ # Diagramas Mermaid: ```mermaid … ``` se renderiza como diagrama vectorial.
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.highlight:
@@ -147,7 +170,14 @@ nav:
- Leer las 5 redes: guias/leer-redes.md
- Del corpus al reporte: guias/reporte.md
- Referencia:
- - API de Python: reference/python-api.md
+ - API de Python:
+ - reference/python-api/index.md
+ - Corpus y persistencia: reference/python-api/corpus.md
+ - Fuentes (siembra): reference/python-api/fuentes.md
+ - Forrajeo y curación: reference/python-api/forrajeo.md
+ - Redes (proyección): reference/python-api/redes.md
+ - Análisis de redes: reference/python-api/analisis.md
+ - Exportadores: reference/python-api/exportadores.md
- CLI b2g: reference/cli.md
- Glosario: reference/glosario.md
- Contribuye:
diff --git a/src/bib2graph/backends/duckdb.py b/src/bib2graph/backends/duckdb.py
index 561d5ec..fd499ea 100644
--- a/src/bib2graph/backends/duckdb.py
+++ b/src/bib2graph/backends/duckdb.py
@@ -988,7 +988,7 @@ def persist_filter_steps(
) -> None:
"""Persiste los pasos de filtro PRISMA en ``filter_log``.
- #126 — trazabilidad PRISMA: los pasos aplicados en ``b2g filter``
+ Ref #126 — trazabilidad PRISMA: los pasos aplicados en ``b2g filter``
se guardan para que ``manifest.filters`` sobreviva entre cargas del
store.
@@ -1020,7 +1020,7 @@ def persist_filter_steps(
def load_filter_steps(self) -> list[dict[str, object]]:
"""Carga los pasos de filtro PRISMA desde ``filter_log``.
- #126 — trazabilidad PRISMA: permite que ``DuckDBStore.load()``
+ Ref #126 — trazabilidad PRISMA: permite que ``DuckDBStore.load()``
reconstruya ``manifest.filters`` con los pasos persistidos.
Returns:
@@ -1051,7 +1051,7 @@ def persist_enricher_refs(
) -> None:
"""Persiste las referencias de enriquecedor en ``enricher_log``.
- #141 — trazabilidad de enriquecimiento: los ``EnricherRef`` aplicados
+ Ref #141 — trazabilidad de enriquecimiento: los ``EnricherRef`` aplicados
en ``b2g enrich`` / ``b2g chain`` / ``b2g build`` se guardan para que
``manifest.enrichers`` sobreviva entre cargas del store.
@@ -1078,7 +1078,7 @@ def persist_enricher_refs(
def load_enricher_refs(self) -> list[dict[str, Any]]:
"""Carga las referencias de enriquecedor desde ``enricher_log``.
- #141 — trazabilidad de enriquecimiento: permite que
+ Ref #141 — trazabilidad de enriquecimiento: permite que
``DuckDBStore.load()`` reconstruya ``manifest.enrichers`` con los
EnricherRef persistidos.
diff --git a/src/bib2graph/backends/memory.py b/src/bib2graph/backends/memory.py
index 04df27b..ef969fc 100644
--- a/src/bib2graph/backends/memory.py
+++ b/src/bib2graph/backends/memory.py
@@ -349,7 +349,7 @@ class InMemoryBackend:
Semántica de valor: todas las operaciones mutantes devuelven una nueva
instancia; la original no cambia nunca.
- #54: almacena también los IDs backward observados en ``_referenced_refs``
+ Ref #54: almacena también los IDs backward observados en ``_referenced_refs``
(lista en memoria, equivalente a la tabla ``referenced_but_not_fetched``
de ``DuckDBBackend``).
"""
diff --git a/src/bib2graph/cli/commands/networks.py b/src/bib2graph/cli/commands/networks.py
index 6e8b0f8..16be3e3 100644
--- a/src/bib2graph/cli/commands/networks.py
+++ b/src/bib2graph/cli/commands/networks.py
@@ -21,7 +21,7 @@
DEPRECADO (ADR 0038, #165): usar ``b2g build --spec``. Se retira en 0.11.0.
-#159 — helper compartido:
+Ref #159 — helper compartido:
``run_networks`` delega la carga YAML y proyección a ``_build_from_spec_file``
(definido en ``build.py``). Esto garantiza que ``build --spec`` y
``networks --spec`` nunca diverjan, y que #165 pueda retirar ``networks``
diff --git a/src/bib2graph/stores/duckdb.py b/src/bib2graph/stores/duckdb.py
index 86a4474..e3325aa 100644
--- a/src/bib2graph/stores/duckdb.py
+++ b/src/bib2graph/stores/duckdb.py
@@ -76,9 +76,9 @@ def load(self) -> Corpus:
archivo; las operaciones subsecuentes (``accept``, ``reject``,
``merge``) mutarán el archivo en disco.
- #126: reconstruye ``manifest.filters`` desde ``filter_log`` para que
+ Ref #126: reconstruye ``manifest.filters`` desde ``filter_log`` para que
los pasos PRISMA persistan entre sesiones.
- #141: reconstruye ``manifest.enrichers`` desde ``enricher_log`` para
+ Ref #141: reconstruye ``manifest.enrichers`` desde ``enricher_log`` para
que los ``EnricherRef`` persistan entre sesiones.
Returns:
diff --git a/uv.lock b/uv.lock
index 5d2f786..2fdcfe4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -101,7 +101,7 @@ wheels = [
[[package]]
name = "bib2graph"
-version = "0.10.1"
+version = "0.11.0"
source = { editable = "." }
dependencies = [
{ name = "click" },