From bd8a34341d225e903a1c699401f21d2f4e4374fe Mon Sep 17 00:00:00 2001
From: Manuel Cillero <manuel@cillero.es>
Date: Sat, 9 May 2026 13:33:20 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=A7=20Retoques=20en=20documentaci?=
 =?UTF-8?q?=C3=B3n=20y=20c=C3=B3digo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 extensions/pagetop-aliner/src/lib.rs    |   5 +-
 extensions/pagetop-seaorm/src/config.rs |  22 ++---
 extensions/pagetop-seaorm/src/lib.rs    | 113 +++++++++++++++++++++++-
 3 files changed, 119 insertions(+), 21 deletions(-)

diff --git a/extensions/pagetop-aliner/src/lib.rs b/extensions/pagetop-aliner/src/lib.rs
index 7a29eebc..e88a9142 100644
--- a/extensions/pagetop-aliner/src/lib.rs
+++ b/extensions/pagetop-aliner/src/lib.rs
@@ -85,9 +85,10 @@ use pagetop::prelude::*;
 
 include_locales!(LOCALES_ALINER);
 
-/// Implementa el tema para usar en pruebas que muestran el esquema de páginas HTML.
+/// Implementa el tema.
 ///
-/// Define un tema mínimo útil para:
+/// Define un tema mínimo que muestra esquemáticamente la composición de las páginas HTML; útil
+/// para:
 ///
 /// - Comprobar el funcionamiento de temas, plantillas y regiones.
 /// - Verificar integración de componentes y composiciones (*layouts*) sin estilos complejos.
diff --git a/extensions/pagetop-seaorm/src/config.rs b/extensions/pagetop-seaorm/src/config.rs
index 5c706659..bec565b3 100644
--- a/extensions/pagetop-seaorm/src/config.rs
+++ b/extensions/pagetop-seaorm/src/config.rs
@@ -16,8 +16,7 @@
 //! Uso:
 //!
 //! ```rust
-//! use pagetop_seaorm::config;
-//!
+//! # use pagetop_seaorm::config;
 //! assert_eq!(config::SETTINGS.database.db_host, "localhost");
 //! ```
 //!
@@ -30,12 +29,12 @@ use serde::Deserialize;
 
 include_config!(SETTINGS: Settings => [
     // [database]
-    "database.db_type"      => "",
-    "database.db_name"      => "",
-    "database.db_user"      => "",
-    "database.db_pass"      => "",
-    "database.db_host"      => "localhost",
-    "database.db_port"      => 0,
+    "database.db_type"       => "",
+    "database.db_name"       => "",
+    "database.db_user"       => "",
+    "database.db_pass"       => "",
+    "database.db_host"       => "localhost",
+    "database.db_port"       => 0,
     "database.max_pool_size" => 5,
 ]);
 
@@ -49,24 +48,17 @@ pub struct Settings {
 /// Sección `[database]` de la configuración. Forma parte de [`Settings`].
 pub struct Database {
     /// Tipo de base de datos: *"mysql"*, *"postgres"* ó *"sqlite"*.
-    /// Por defecto: *""*.
     pub db_type: String,
     /// Nombre (para mysql/postgres) o referencia (para sqlite) de la base de datos.
-    /// Por defecto: *""*.
     pub db_name: String,
     /// Usuario de conexión a la base de datos (para mysql/postgres).
-    /// Por defecto: *""*.
     pub db_user: String,
     /// Contraseña para la conexión a la base de datos (para mysql/postgres).
-    /// Por defecto: *""*.
     pub db_pass: String,
     /// Servidor de conexión a la base de datos (para mysql/postgres).
-    /// Por defecto: *"localhost"*.
     pub db_host: String,
     /// Puerto de conexión a la base de datos, normalmente 3306 (para mysql) ó 5432 (para postgres).
-    /// Por defecto: *0*.
     pub db_port: u16,
     /// Número máximo de conexiones habilitadas.
-    /// Por defecto: *5*.
     pub max_pool_size: u32,
 }
diff --git a/extensions/pagetop-seaorm/src/lib.rs b/extensions/pagetop-seaorm/src/lib.rs
index b9928727..64578cb8 100644
--- a/extensions/pagetop-seaorm/src/lib.rs
+++ b/extensions/pagetop-seaorm/src/lib.rs
@@ -1,17 +1,122 @@
+/*!
+<div align="center">
+
+<h1>PageTop SeaORM</h1>
+
+<p>Proporciona a <strong>PageTop</strong> acceso basado en <a href="https://www.sea-ql.org/SeaORM">SeaORM</a> a bases de datos relacionales.</p>
+
+[![Doc API](https://img.shields.io/docsrs/pagetop-seaorm?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-seaorm)
+[![Crates.io](https://img.shields.io/crates/v/pagetop-seaorm.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-seaorm)
+[![Descargas](https://img.shields.io/crates/d/pagetop-seaorm.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-seaorm)
+[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-seaorm#licencia)
+
+</div>
+
+## 🧭 Sobre PageTop
+
+[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
+clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
+configurables, basadas en HTML, CSS y JavaScript.
+
+
+## ⚡️ Guía rápida
+
+**Añade la dependencia** a tu `Cargo.toml` activando el motor de base de datos que necesites:
+
+```toml
+[dependencies]
+pagetop-seaorm = { version = "...", features = ["sqlite"] }
+```
+
+Las *features* disponibles son `mysql`, `postgres` y `sqlite`.
+
+**Configura la conexión** en el archivo de configuración de la aplicación:
+
+```toml
+[database]
+db_type = "sqlite"
+db_name = "my_app.db"
+max_pool_size = 5
+```
+
+Para MySQL o PostgreSQL añade también `db_user`, `db_pass`, `db_host` y `db_port`.
+
+**Declara la extensión** en tu aplicación o en la extensión que la requiera:
+
+```rust,no_run
 use pagetop::prelude::*;
 
+struct MyApp;
+
+impl Extension for MyApp {
+    fn dependencies(&self) -> Vec<ExtensionRef> {
+        vec![
+            &pagetop_seaorm::SeaORM,
+        ]
+    }
+
+    fn initialize(&self) {
+        install_migrations!(m20240101_000001_create_users_table);
+    }
+}
+
+#[pagetop::main]
+async fn main() -> std::io::Result<()> {
+    Application::prepare(&MyApp).run()?.await
+}
+```
+
+**Escribe las migraciones** usando la API de SeaORM:
+
+```rust,no_run
+use pagetop_seaorm::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .create_table(
+                table_auto(Users::Table)
+                    .col(pk_auto(Users::Id))
+                    .col(string_uniq(Users::Email))
+                    .to_owned(),
+            )
+            .await
+    }
+}
+
+#[derive(DeriveIden)]
+enum Users {
+    Table,
+    Id,
+    Email,
+}
+```
+*/
+
+#![doc(
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+)]
+
+use pagetop::prelude::*;
+
+include_locales!(LOCALES_SEAORM);
+
 pub mod config;
+
 pub mod db;
 
-/// Preludio de la extensión.
+/// *Prelude* de la extensión.
 pub mod prelude {
+    pub use crate::config::*;
     pub use crate::db::*;
     pub use crate::install_migrations;
 }
 
-include_locales!(LOCALES_SEAORM);
-
-/// Extensión que integra SeaORM como framework de base de datos para aplicaciones PageTop.
+/// Implementa la extensión.
 pub struct SeaORM;
 
 impl Extension for SeaORM {