Document pagetop-mail (configuration, templates, layout, previews, queue and tests with the outbox) and file uploads (`web::Upload`, `form::File`, `web::Download` and the [upload] settings). doccheck enables the mail queue, keeps mail in memory and saves uploads under `target/`.
135 lines
6.6 KiB
Markdown
135 lines
6.6 KiB
Markdown
<div align="center">
|
|
|
|
<h1>PageTop Website</h1>
|
|
|
|
<p>Official website of <strong>PageTop</strong>, to introduce this development environment to the community.</p>
|
|
|
|
[](#license)
|
|
|
|
</div>
|
|
|
|
## Overview
|
|
|
|
Web application built with [PageTop](https://docs.rs/pagetop) to present its own ecosystem to the
|
|
community, available at [pagetop.cillero.es](https://pagetop.cillero.es). It is the entry point to
|
|
the PageTop guides for developers and users.
|
|
|
|
The guides are [mdBook](https://rust-lang.github.io/mdBook/) books under `doc/`, one per version and
|
|
language (`doc/<version>/<language>/`), all of them with the theme in `doc/theme/`. They are built
|
|
and embedded into the binary when the application is compiled, and served as PageTop pages with
|
|
[pagetop-mdbook](https://git.cillero.es/manuelcillero/pagetop-mdbook).
|
|
|
|
## Requirements
|
|
|
|
- Rust (edition 2024).
|
|
- [mdBook](https://rust-lang.github.io/mdBook/) 0.4 on the `PATH`, to build the guides (`cargo
|
|
install mdbook --version "^0.4"`).
|
|
- The `pagetop` and `pagetop-mdbook` repositories next to this one, as in the `pagetop-projects`
|
|
workspace: the dependencies use relative paths.
|
|
|
|
## Running
|
|
|
|
```sh
|
|
cargo run
|
|
```
|
|
|
|
The server listens on `0.0.0.0:8080` by default. Routes:
|
|
|
|
| Route | Content |
|
|
|-----------------------------|------------------------------------------------------|
|
|
| `/` | PageTop welcome page |
|
|
| `/doc/latest/{lang}` | Redirects to the latest guides (Spanish only, by now)|
|
|
| `/doc/<version>/<lang>/...` | Chapters of the guides |
|
|
|
|
The books are built into `static/doc/` (not versioned) only when their sources change. The version
|
|
that `/doc/latest/{lang}` points to, and the languages of the guides, are set in `src/lib.rs`
|
|
(`LATEST_DOC` and `DOC_LANGUAGES`).
|
|
|
|
## Checking the guides
|
|
|
|
The guides document the current PageTop code, so they must be checked again whenever PageTop
|
|
changes. `tools/doccheck.sh` does it in one step:
|
|
|
|
```sh
|
|
tools/doccheck.sh # the latest Spanish guide (doc/v0.6/es)
|
|
tools/doccheck.sh doc/v0.7/es # any other book
|
|
```
|
|
|
|
It needs `mdbook` and `python3`, and the `pagetop` repository next to this one. It runs three
|
|
checks and ends with exit code 1 if any fails:
|
|
|
|
1. **Links.** Builds the book and checks that every internal link points to an existing page and
|
|
anchor.
|
|
2. **Examples.** Extracts every ```` ```rust ```` block into `tools/doccheck/examples/`, removing
|
|
the `# ` prefix of the lines that mdBook hides, and compiles them against PageTop. Blocks not
|
|
marked `no_run` are also executed, so their `assert!` are checked.
|
|
3. **Tests.** Blocks with `#[pagetop::test]` become tests, and run with `cargo test` together with
|
|
the fixed tests in `tools/doccheck/tests/` (for example, `localization.rs` checks the
|
|
translations of the localization chapter at run time).
|
|
|
|
### How the guides are organized
|
|
|
|
Each book follows the four kinds of documentation of [Diátaxis](https://diataxis.fr), one folder
|
|
each:
|
|
|
|
| Folder | Kind | Shape of a page |
|
|
|---|---|---|
|
|
| `tutorials/` | Learning by doing, in order | Time, prerequisites and result; numbered steps that run; "what you built"; next steps |
|
|
| `how-to/` | One task | A **goal** line; numbered steps; the complete example; how to check it; next steps |
|
|
| `reference/` | Looking things up | Tables: options, components, attributes |
|
|
| `explanation/` | The why | Prose and diagrams, few examples |
|
|
|
|
Every page ends linking the next ones to read. The interactive (HTMX) pages end with a complete,
|
|
runnable example. `doccheck.sh` compiles it, but what happens in the browser is only declared by its
|
|
`hx-*` attributes: after changing one of them, run it and try it in a browser.
|
|
|
|
When writing a chapter:
|
|
|
|
- Write the examples **in English**, whatever the language of the guide: identifiers, strings,
|
|
comments, paths and configuration values. Translating a guide is then only translating its
|
|
text. Use another language only where the example needs it (such as the Spanish values of an
|
|
`es-ES` translation file).
|
|
- Write every example as **complete, compilable code**. Hide the lines the reader does not need
|
|
(imports, a wrapping function, helper stubs) with a leading `# `; mdBook does not show them.
|
|
- Use ```` ```rust ```` only for examples that can run with no server (with `assert!`),
|
|
```` ```rust,no_run ```` for the rest, and ```` ```rust,ignore ```` only for loose fragments
|
|
that are not valid on their own.
|
|
- Examples can use `pagetop`, `pagetop-admin`, `pagetop-bootsier`, `pagetop-cron`,
|
|
`pagetop-htmx`, `pagetop-mail` (with its `queue` feature), `pagetop-seaorm` (with SQLite),
|
|
`pagetop-user`, `pagetop-build`, `serde`, `thiserror`, `tokio` and `tower-http` (with the
|
|
`compression-gzip`, `cors`, `limit` and `timeout` features); the translations in
|
|
`tools/doccheck/src/locale/` (`LOCALES_APP`), and a static files bundle named `app`. If a chapter needs anything else, add it to `tools/doccheck`.
|
|
- Examples and tests that start an application read `tools/doccheck/config/`: those with a database
|
|
get a new in-memory SQLite one on every run, mail is kept in memory (`pagetop_mail::outbox`) and
|
|
uploaded files go to `tools/doccheck/target/doccheck-uploads`.
|
|
- Tests that share state (a static store, a database) run in the same process: write one test per
|
|
flow, so that their results do not depend on the order they run in.
|
|
|
|
The first run compiles PageTop and takes a few minutes; the next ones only compile the examples.
|
|
|
|
## Configuration
|
|
|
|
Settings are loaded in cascade from the `config/` directory (or the one in the `CONFIG_DIR`
|
|
environment variable): `common.toml`, then `{run_mode}.toml` according to `PAGETOP_RUN_MODE`
|
|
(`default` by default), `local.{run_mode}.toml` and `local.toml`. The local files are not
|
|
versioned. Finally, environment variables named `PAGETOP_<SECTION>__<KEY>` override individual
|
|
keys (e.g. `PAGETOP_SERVER__BIND_PORT=80`).
|
|
|
|
## Warning
|
|
|
|
**PageTop** is a personal project to learn [Rust](https://www.rust-lang.org/) and its ecosystem. Its
|
|
API is subject to frequent changes. Production use is not recommended, at least until version
|
|
**1.0.0** is released.
|
|
|
|
## License
|
|
|
|
The code is available under a dual license:
|
|
|
|
* **MIT License**
|
|
([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
|
|
|
|
* **Apache License, Version 2.0**
|
|
([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
You may choose either license. This dual-license approach is the de facto standard in the Rust
|
|
ecosystem.
|