📝 Cambia el formato para la documentación

This commit is contained in:
Manuel Cillero 2025-08-10 01:03:35 +02:00
parent 489dd8dfe2
commit 3789800713
8 changed files with 404 additions and 256 deletions

View file

@ -18,6 +18,107 @@ clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares
configurables, basadas en HTML, CSS y JavaScript.
# ⚡️ Guía rápida
Añadir en el archivo `Cargo.toml` del proyecto:
```toml
[build-dependencies]
pagetop-build = { ... }
```
Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
## Incluir archivos estáticos desde un directorio
Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
```rust,no_run
use pagetop_build::StaticFilesBundle;
fn main() -> std::io::Result<()> {
StaticFilesBundle::from_dir("./static", None)
.with_name("guides")
.build()
}
```
Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
ejemplo:
```rust,no_run
use pagetop_build::StaticFilesBundle;
use std::path::Path;
fn main() -> std::io::Result<()> {
fn only_pdf_files(path: &Path) -> bool {
// Selecciona únicamente los archivos con extensión `.pdf`.
path.extension().map_or(false, |ext| ext == "pdf")
}
StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
.with_name("guides")
.build()
}
```
## Compilar archivos SCSS a CSS
Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
el archivo CSS minificado obtenido. Por ejemplo:
```rust,no_run
use pagetop_build::StaticFilesBundle;
fn main() -> std::io::Result<()> {
StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
.with_name("main_styles")
.build()
}
```
Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
# 📦 Módulos generados
Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
donde se incluyen los recursos necesarios para compilar el proyecto. Por ejemplo, para
`with_name("guides")` se crea un archivo llamado `guides.rs`.
No hay ningún problema en generar más de un conjunto de recursos para cada proyecto.
Normalmente no habrá que acceder a estos módulos; bastará con incluirlos en el proyecto con
[`include_files!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files.html), y luego con
[`include_files_service!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files_service.html)
configurar un servicio web para servir los recursos desde la ruta indicada:
```rust,ignore
use pagetop::prelude::*;
include_files!(guides);
pub struct MyExtension;
impl Extension for MyExtension {
// Servicio web que publica los recursos de `guides` en `/ruta/a/guides`.
fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
include_files_service!(scfg, guides => "/ruta/a/guides");
}
}
```
También se puede asignar el conjunto de recursos a una variable global; p.ej. `GUIDES`:
```rust,ignore
include_files!(GUIDES => guides);
```
# 🚧 Advertencia
`PageTop` es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su

View file

@ -1,122 +1,124 @@
//! <div align="center">
//!
//! <h1>PageTop Build</h1>
//!
//! <p>Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto <strong>PageTop</strong>.</p>
//!
//! [![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](#-licencia)
//! [![Doc API](https://img.shields.io/docsrs/pagetop-build?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-build)
//! [![Crates.io](https://img.shields.io/crates/v/pagetop-build.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-build)
//! [![Descargas](https://img.shields.io/crates/d/pagetop-build.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-build)
//!
//! </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ñadir en el archivo `Cargo.toml` del proyecto:
//!
//! ```toml
//! [build-dependencies]
//! pagetop-build = { ... }
//! ```
//!
//! Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
//! archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
//!
//! ## Incluir archivos estáticos desde un directorio
//!
//! Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
//! ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
//!
//! ```rust,no_run
//! use pagetop_build::StaticFilesBundle;
//!
//! fn main() -> std::io::Result<()> {
//! StaticFilesBundle::from_dir("./static", None)
//! .with_name("guides")
//! .build()
//! }
//! ```
//!
//! Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta,
//! por ejemplo:
//!
//! ```rust,no_run
//! use pagetop_build::StaticFilesBundle;
//! use std::path::Path;
//!
//! fn main() -> std::io::Result<()> {
//! fn only_pdf_files(path: &Path) -> bool {
//! // Selecciona únicamente los archivos con extensión `.pdf`.
//! path.extension().map_or(false, |ext| ext == "pdf")
//! }
//!
//! StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
//! .with_name("guides")
//! .build()
//! }
//! ```
//!
//! ## Compilar archivos SCSS a CSS
//!
//! Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso
//! con el archivo CSS minificado obtenido. Por ejemplo:
//!
//! ```rust,no_run
//! use pagetop_build::StaticFilesBundle;
//!
//! fn main() -> std::io::Result<()> {
//! StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
//! .with_name("main_styles")
//! .build()
//! }
//! ```
//!
//! Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un
//! recurso llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
//!
//!
//! # 📦 Módulos generados
//!
//! Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
//! [OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
//! donde se incluyen los recursos necesarios para compilar el proyecto. Por ejemplo, para
//! `with_name("guides")` se crea un archivo llamado `guides.rs`.
//!
//! No hay ningún problema en generar más de un conjunto de recursos para cada proyecto.
//!
//! Normalmente no habrá que acceder a estos módulos; bastará con incluirlos en el proyecto con
//! [`include_files!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files.html), y luego con
//! [`include_files_service!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files_service.html)
//! configurar un servicio web para servir los recursos desde la ruta indicada:
//!
//! ```rust,ignore
//! use pagetop::prelude::*;
//!
//! include_files!(guides);
//!
//! pub struct MyExtension;
//!
//! impl Extension for MyExtension {
//! // Servicio web que publica los recursos de `guides` en `/ruta/a/guides`.
//! fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
//! include_files_service!(scfg, guides => "/ruta/a/guides");
//! }
//! }
//! ```
//!
//! También se puede asignar el conjunto de recursos a una variable global; p.ej. `GUIDES`:
//!
//! ```rust,ignore
//! include_files!(GUIDES => guides);
//! ```
/*!
<div align="center">
<h1>PageTop Build</h1>
<p>Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto <strong>PageTop</strong>.</p>
[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](#-licencia)
[![Doc API](https://img.shields.io/docsrs/pagetop-build?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-build)
[![Crates.io](https://img.shields.io/crates/v/pagetop-build.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-build)
[![Descargas](https://img.shields.io/crates/d/pagetop-build.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-build)
</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ñadir en el archivo `Cargo.toml` del proyecto:
```toml
[build-dependencies]
pagetop-build = { ... }
```
Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
## Incluir archivos estáticos desde un directorio
Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
```rust,no_run
use pagetop_build::StaticFilesBundle;
fn main() -> std::io::Result<()> {
StaticFilesBundle::from_dir("./static", None)
.with_name("guides")
.build()
}
```
Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
ejemplo:
```rust,no_run
use pagetop_build::StaticFilesBundle;
use std::path::Path;
fn main() -> std::io::Result<()> {
fn only_pdf_files(path: &Path) -> bool {
// Selecciona únicamente los archivos con extensión `.pdf`.
path.extension().map_or(false, |ext| ext == "pdf")
}
StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
.with_name("guides")
.build()
}
```
## Compilar archivos SCSS a CSS
Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
el archivo CSS minificado obtenido. Por ejemplo:
```rust,no_run
use pagetop_build::StaticFilesBundle;
fn main() -> std::io::Result<()> {
StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
.with_name("main_styles")
.build()
}
```
Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
# 📦 Módulos generados
Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
donde se incluyen los recursos necesarios para compilar el proyecto. Por ejemplo, para
`with_name("guides")` se crea un archivo llamado `guides.rs`.
No hay ningún problema en generar más de un conjunto de recursos para cada proyecto.
Normalmente no habrá que acceder a estos módulos; bastará con incluirlos en el proyecto con
[`include_files!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files.html), y luego con
[`include_files_service!`](https://docs.rs/pagetop/latest/pagetop/macro.include_files_service.html)
configurar un servicio web para servir los recursos desde la ruta indicada:
```rust,ignore
use pagetop::prelude::*;
include_files!(guides);
pub struct MyExtension;
impl Extension for MyExtension {
// Servicio web que publica los recursos de `guides` en `/ruta/a/guides`.
fn configure_service(&self, scfg: &mut service::web::ServiceConfig) {
include_files_service!(scfg, guides => "/ruta/a/guides");
}
}
```
También se puede asignar el conjunto de recursos a una variable global; p.ej. `GUIDES`:
```rust,ignore
include_files!(GUIDES => guides);
```
*/
#![doc(
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"

View file

@ -11,9 +11,16 @@
</div>
## Descripción general
## Sobre PageTop
Entre sus macros se incluye una adaptación de [maud-macros](https://crates.io/crates/maud_macros)
[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.
## Créditos
Esta librería incluye entre sus macros una adaptación de
[maud-macros](https://crates.io/crates/maud_macros)
([0.27.0](https://github.com/lambda-fairy/maud/tree/v0.27.0/maud_macros)) de
[Chris Wong](https://crates.io/users/lambda-fairy) y una versión renombrada de
[SmartDefault](https://crates.io/crates/smart_default) (0.7.1) de
@ -21,12 +28,6 @@ Entre sus macros se incluye una adaptación de [maud-macros](https://crates.io/c
necesidad de referenciar `maud` o `smart_default` en las dependencias del archivo `Cargo.toml` de
cada proyecto `PageTop`.
## 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.
# 🚧 Advertencia

View file

@ -1,21 +1,34 @@
//! <div align="center">
//!
//! <h1>PageTop Macros</h1>
//!
//! <p>Una colección de macros que mejoran la experiencia de desarrollo con <strong>PageTop</strong>.</p>
//!
//! [![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](#-licencia)
//! [![Doc API](https://img.shields.io/docsrs/pagetop-macros?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-macros)
//! [![Crates.io](https://img.shields.io/crates/v/pagetop-macros.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-macros)
//! [![Descargas](https://img.shields.io/crates/d/pagetop-macros.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-macros)
//!
//! </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.
/*!
<div align="center">
<h1>PageTop Macros</h1>
<p>Una colección de macros que mejoran la experiencia de desarrollo con <strong>PageTop</strong>.</p>
[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](#-licencia)
[![Doc API](https://img.shields.io/docsrs/pagetop-macros?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-macros)
[![Crates.io](https://img.shields.io/crates/v/pagetop-macros.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-macros)
[![Descargas](https://img.shields.io/crates/d/pagetop-macros.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-macros)
</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.
## Créditos
Esta librería incluye entre sus macros una adaptación de
[maud-macros](https://crates.io/crates/maud_macros)
([0.27.0](https://github.com/lambda-fairy/maud/tree/v0.27.0/maud_macros)) de
[Chris Wong](https://crates.io/users/lambda-fairy) y una versión renombrada de
[SmartDefault](https://crates.io/crates/smart_default) (0.7.1) de
[Jane Doe](https://crates.io/users/jane-doe), llamada `AutoDefault`. Estas macros eliminan la
necesidad de referenciar `maud` o `smart_default` en las dependencias del archivo `Cargo.toml` de
cada proyecto `PageTop`.
*/
#![doc(
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"

View file

@ -8,12 +8,21 @@
</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.
## Descripción general
Permite a `PageTop` incluir archivos estáticos en el ejecutable de la aplicación para servirlos de
forma eficiente vía web, con detección de cambios que optimiza el tiempo de compilación.
Esta librería permite incluir archivos estáticos en el ejecutable de las aplicaciones `PageTop` para
servirlos de forma eficiente vía web, con detección de cambios que optimizan el tiempo de
compilación.
Para ello, reúne el código de los *crates* [static-files](https://crates.io/crates/static_files)
## Créditos
Para ello, adapta el código de los *crates* [static-files](https://crates.io/crates/static_files)
(versión [0.2.5](https://github.com/static-files-rs/static-files/tree/v0.2.5)) y
[actix-web-static-files](https://crates.io/crates/actix_web_static_files) (versión
[4.0.1](https://github.com/kilork/actix-web-static-files/tree/v4.0.1)), desarrollados ambos por
@ -22,12 +31,6 @@ Para ello, reúne el código de los *crates* [static-files](https://crates.io/cr
Estas implementaciones se integran en `PageTop` para evitar que cada proyecto tenga que declarar
`static-files` manualmente como dependencia en su `Cargo.toml`.
## 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.
# 🚧 Advertencia

View file

@ -1,18 +1,37 @@
//! <div align="center">
//!
//! <h1>PageTop Statics</h1>
//!
//! <p>Librería para automatizar la recopilación de recursos estáticos en <strong>PageTop</strong>.</p>
//!
//! [![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](#-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.
/*!
<div align="center">
<h1>PageTop Statics</h1>
<p>Librería para automatizar la recopilación de recursos estáticos en <strong>PageTop</strong>.</p>
[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](#-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.
## Descripción general
Esta librería permite incluir archivos estáticos en el ejecutable de las aplicaciones `PageTop` para
servirlos de forma eficiente vía web, con detección de cambios que optimizan el tiempo de
compilación.
## Créditos
Para ello, adapta el código de los *crates* [static-files](https://crates.io/crates/static_files)
(versión [0.2.5](https://github.com/static-files-rs/static-files/tree/v0.2.5)) y
[actix-web-static-files](https://crates.io/crates/actix_web_static_files) (versión
[4.0.1](https://github.com/kilork/actix-web-static-files/tree/v4.0.1)), desarrollados ambos por
[Alexander Korolev](https://crates.io/users/kilork).
Estas implementaciones se integran en `PageTop` para evitar que cada proyecto tenga que declarar
`static-files` manualmente como dependencia en su `Cargo.toml`.
*/
#![doc(test(no_crate_inject))]
#![doc(