📝 Refine docs and review config setup

packages/pagetop-seaorm/src/db/migration/schema.rs

@@ -1,4 +1,4 @@
-//! > Adapted from https://github.com/loco-rs/loco/blob/master/src/schema.rs
+//! > Adapted from <https://github.com/loco-rs/loco/blob/master/src/schema.rs>
 //!
 //! # Database Table Schema Helpers
 //!

packages/pagetop-seaorm/src/lib.rs

@@ -13,7 +13,7 @@ pub mod prelude {
 
 include_locales!(LOCALES_SEAORM);
 
-/// Implements [`PackageTrait`](pagetop::core::package::PackageTrait) and specific package API.
+/// Implements [`PackageTrait`] and specific package API.
 pub struct SeaORM;
 
 impl PackageTrait for SeaORM {

pagetop/src/config.rs

@@ -1,67 +1,67 @@
-//! Retrieve settings values from configuration files.
+//! Load configuration settings.
 //!
-//! Define un conjunto de ajustes de configuración usando tipos seguros y valores predefinidos.
+//! These settings are loaded from [TOML](https://toml.io) files as `key = value` pairs and mapped
+//! into type-safe structures with predefined values.
 //!
-//! Detiene la aplicación con un panic! si no pueden asignarse los ajustes de configuración.
+//! The [Twelve-Factor App](https://12factor.net/config) methodology defines **application
+//! configuration as everything that varies across deployments**, such as development, staging,
+//! or production environments.
 //!
-//! Carga la configuración de la aplicación en forma de pares `clave = valor` recogidos en archivos
+//! Storing configuration values as code constants violates this methodology. `PageTop` advocates
-//! [TOML](https://toml.io).
+//! for a **strict separation between code and configuration**, ensuring configuration varies per
-//!
+//! deployment while the code remains constant.
-//! La metodología [The Twelve-Factor App](https://12factor.net/es/) define **la configuración de
-//! una aplicación como todo lo que puede variar entre despliegues**, diferenciando entre entornos
-//! de desarrollo, pre-producción, producción, etc.
-//!
-//! A veces las aplicaciones guardan configuraciones como constantes en el código, lo que implica
-//! una violación de esta metodología. `PageTop` recomienda una **estricta separación entre código y
-//! configuración**. La configuración variará en cada tipo de despliegue, y el código no.
 //!
 //!
-//! # Cómo cargar los ajustes de configuración
+//! # Loading configuration settings
 //!
-//! Si tu aplicación requiere archivos de configuración debes crear un directorio *config* al mismo
+//! If your application requires configuration files, create a `config` directory in the root of
-//! nivel del archivo *Cargo.toml* de tu proyecto (o del ejecutable binario de la aplicación).
+//! your project, at the same level as the *Cargo.toml* file or the application's binary.
 //!
-//! `PageTop` se encargará de cargar todos los ajustes de configuración de tu aplicación leyendo los
+//! `PageTop` automatically loads configuration settings by reading the following TOML files in
-//! siguientes archivos TOML en este orden (todos los archivos son opcionales):
+//! order (all files are optional):
 //!
-//! 1. **config/common.toml**, útil para los ajustes comunes a cualquier entorno. Estos valores
+//! 1. **config/common.toml**: Contains settings shared across all environments. These values can be
-//!    podrán ser sobrescritos al fusionar los archivos de configuración restantes.
+//!    overridden by the subsequent files.
 //!
-//! 2. **config/{file}.toml**, donde *{file}* se define con la variable de entorno
+//! 2. **config/{file}.toml**, where `{file}` corresponds to the environment variable
 //!    `PAGETOP_RUN_MODE`:
 //!
-//!     * Si no está definida se asumirá *default* por defecto y `PageTop` intentará cargar el
+//!     * If `PAGETOP_RUN_MODE` is not set, it defaults to `default`, and `PageTop` attempts to load
-//!       archivo *config/default.toml* si existe.
+//!       *config/default.toml* if available.
 //!
-//!     * De esta manera podrás tener diferentes ajustes de configuración para diferentes entornos
+//!     * This enables separate configurations for environments like *devel.toml*, *staging.toml*,
-//!       de ejecución. Por ejemplo, para *devel.toml*, *staging.toml* o *production.toml*. O
+//!       or *production.toml*, or setups such as *server1.toml*. Only one file will be loaded.
-//!       también para *server1.toml* o *server2.toml*. Sólo uno será cargado.
 //!
-//!     * Normalmente estos archivos suelen ser idóneos para incluir contraseñas o configuración
+//!     * These files are suitable for storing sensitive values like passwords. Avoid committing
-//!       sensible asociada al entorno correspondiente. Estos archivos no deberían ser publicados en
+//!       them to Git for security reasons.
-//!       el repositorio Git por razones de seguridad.
 //!
-//! 3. **config/local.toml**, para añadir o sobrescribir ajustes de los archivos anteriores.
+//! 3. **config/local.toml**: Used to add or override settings from the previous files.
 //!
 //!
-//! # Cómo añadir ajustes de configuración
+//! # Adding configuration settings
 //!
-//! Para proporcionar a tu **módulo** sus propios ajustes de configuración, añade
+//! To give your **module** its own configuration settings, add [*serde*](https://docs.rs/serde) as
-//! [*serde*](https://docs.rs/serde) en las dependencias de tu archivo *Cargo.toml* habilitando la
+//! a dependency in your *Cargo.toml* file with the `derive` feature enabled:
-//! característica `derive`:
 //!
 //! ```toml
 //! [dependencies]
 //! serde = { version = "1.0", features = ["derive"] }
 //! ```
 //!
-//! Y luego inicializa con la macro [`include_config!`](crate::include_config) tus ajustes, usando
+//! Then, use the [`include_config!`](crate::include_config) macro to initialize your settings with
-//! tipos seguros y asignando los valores predefinidos para la estructura asociada:
+//! type-safe structures and predefined values:
 //!
 //! ```
 //! use pagetop::prelude::*;
 //! use serde::Deserialize;
 //!
+//! include_config!(SETTINGS: Settings => [
+//!     // [myapp]
+//!     "myapp.name" => "Value Name",
+//!     "myapp.width" => 900,
+//!     "myapp.height" => 320,
+//! ]);
+//!
 //! #[derive(Debug, Deserialize)]
 //! pub struct Settings {
 //!    pub myapp: MyApp,
@@ -74,31 +74,26 @@
 //!     pub width: u16,
 //!     pub height: u16,
 //! }
-//!
-//! include_config!(SETTINGS: Settings from [
-//!     // [myapp]
-//!     "myapp.name" => "Value Name",
-//!     "myapp.width" => 900,
-//!     "myapp.height" => 320,
-//! ]);
 //! ```
 //!
-//! De hecho, así se declaran los ajustes globales de la configuración (ver [`SETTINGS`]).
+//! This is how global configuration settings are declared (see [`SETTINGS`](crate::global::SETTINGS)).
 //!
-//! Puedes usar la [sintaxis TOML](https://toml.io/en/v1.0.0#table) para añadir tu nueva sección
+//! You can add a new `[myapp]` section in the configuration files using the
-//! `[myapp]` en los archivos de configuración, del mismo modo que se añaden `[log]` o `[server]` en
+//! [TOML syntax](https://toml.io/en/v1.0.0#table), just like the `[log]` or `[server]` sections in
-//! los ajustes globales (ver [`Settings`]).
+//! the global settings (see [`Settings`](crate::global::Settings)).
 //!
-//! Se recomienda inicializar todos los ajustes con valores predefinidos, o utilizar la notación
+//! It is recommended to initialize all settings with predefined values or use `Option<T>` for
-//! `Option<T>` si van a ser tratados en el código como opcionales.
+//! optional settings handled within the code.
 //!
-//! Si no pueden inicializarse correctamente los ajustes de configuración, entonces la aplicación
+//! If configuration settings fail to initialize correctly, the application will panic and stop
-//! ejecutará un panic! y detendrá la ejecución.
+//! execution.
 //!
-//! Los ajustes de configuración siempre serán de sólo lectura.
+//! Configuration settings are always read-only.
 //!
 //!
-//! # Cómo usar tus nuevos ajustes de configuración
+//! # Using your new configuration settings
+//!
+//! Access the settings directly in your code:
 //!
 //! ```
 //! use pagetop::prelude::*;

pagetop/src/lib.rs

@@ -53,7 +53,7 @@
 //! ```
 //! This program implements a package named `HelloWorld` with one service that returns a web page
 //! that greets the world whenever it is accessed from the browser at `http://localhost:8088` (using
-//! the [default configuration settings](`config::Server`)). You can find this code in the `PageTop`
+//! the [default configuration settings](`global::Server`)). You can find this code in the `PageTop`
 //! [examples repository](https://github.com/manuelcillero/pagetop/tree/latest/examples).
 //!
 //! # 🧩 Dependency Management
@@ -91,7 +91,7 @@ pub type Weight = i8;
 
 // Useful functions and macros.
 pub mod util;
-// Retrieve and apply settings values from configuration files.
+// Load configuration settings.
 pub mod config;
 // Application tracing and event logging.
 pub mod trace;