Data-driven config & docs generation, mdBook migration, README rewrite#129
Merged
Data-driven config & docs generation, mdBook migration, README rewrite#129
Conversation
added 15 commits
February 22, 2026 10:26
Extract all hardcoded EN/RU text descriptions from annotated.rs into a structured fields.yaml file (single source of truth). Rust code becomes a compact renderer reading from YAML. From the same YAML, generate both annotated configs (TOML/YAML, EN/RU) and Markdown reference documentation (EN/RU). Changes: - fields.yaml: all field descriptions, section titles, defaults - annotated.rs: refactored from 2757 to ~1450 lines, reads from YAML - docs.rs: new Markdown reference doc generator (EN/RU) - generate-docs CLI subcommand for doc generation - Russian reference docs (documentation/docs/reference/ru/) - mkdocs.yml: added Reference (RU) nav section - 22 tests covering config generation, doc generation, field coverage - Fixed old doc errors: tls_ca_file->tls_ca_cert, tcp_keepalives_interval default 1->5
Replace Python-based mkdocs-material with Rust-native mdBook for documentation. Two separate books: EN (full docs) and RU (reference only) with language switcher. Key changes: - Convert admonitions to mdbook-admonish format, tabbed content to plain sections - Remove YAML frontmatter, Material-specific syntax, changelog attr IDs - Reference docs now generated at build time (not stored in repo) - build.sh generates reference docs, installs plugin assets, builds both books - Pin mdbook@0.4.44, mdbook-admonish@1.20.0, mdbook-mermaid@0.16.2 in CI - Bump rust-toolchain to 1.88.0 (required by mdbook, enables new clippy lints) - Fix all new uninlined_format_args clippy warnings from rustc 1.88 - Update benchmark workflow paths to new documentation structure
Remove Russian mdBook site (keeping --russian flag in generate-docs for future use). Single EN book now builds directly into book/ without subdirectories.
- Replace ASCII art in Patroni Proxy deployment architecture with Mermaid diagram (consistent with overview page style) - Update Configuration File Structure section to mention both YAML and TOML formats (YAML recommended)
Show both YAML (recommended) and TOML configuration examples in the Basic Usage guide, since PgDoorman supports both formats.
Replace TOML snippet and pg_doorman.toml mention with YAML format in the generated Prometheus reference documentation.
Revert rust-toolchain back to 1.87.0 and undo all uninlined_format_args clippy auto-fixes in non-documentation files. mdbook 0.4.44 does not require rustc 1.88.
Reduced README from 342 lines to ~60 lines. Focus on key selling points: drop-in transparent transaction pooling without app changes, battle-tested driver support, 3-4x performance vs PgBouncer, and quick start with auto-config generation. Details moved to docs site.
…tures
- Remove Russian documentation generation from docs.rs (fields.yaml doc entries
now EN-only strings instead of {en, ru} objects). Russian config comments
(--ru flag) are preserved.
- Remove --all-languages and --russian flags from generate-docs command.
- Expand README with detailed comparison table vs PgBouncer/Odyssey, build
instructions with jemalloc tuning, and feature highlights from changelog
(deferred BEGIN, dead connection detection, lifetime jitter, config test mode).
- Clarify benchmarks: PgBouncer is single-threaded and SO_REUSE_PORT with
multiple instances breaks pool balance; Odyssey lacks full extended protocol
support in transaction mode.
…README Quick Start is now self-contained: minimal YAML config with inline server_username/server_password (the #1 setup issue), run command, and application connection string example.
- CI and license badges in header - Benchmark highlights table (4 key scenarios from automated AWS runs) - Compact comparison table vs PgBouncer and Odyssey (11 features) - patroni_proxy section with Mermaid deployment diagram - Fix "Free years" typo to "Two years"
PgBouncer added prepared statement support in transaction mode in version 1.21 via max_prepared_statements setting. Updated comparison table and Why section to accurately reflect this.
Research-backed corrections to the comparison table and text: - Odyssey DOES support prepared statements since v1.3 (was "No") - Odyssey DOES support zero-downtime restart via SO_REUSEPORT (was "No") - Odyssey DOES support pg_hba.conf since v1.4 (was "No (own format)") - PgBouncer DOES support PAM authentication (was "No") - Added new rows: YAML/TOML config, human-readable durations, JWT/LDAP/PAM auth split, config test mode - Reworded "Why PgDoorman?" to use benchmark-based claims instead of absolute statements - Honestly show pg_doorman lacks LDAP auth
vadv
force-pushed
the
feature/data-driven-config-docs
branch
from
6fc66db to
01a2239
Compare
vadv
changed the title
added 2 commits
February 22, 2026 10:34
The benchmark test was still writing to the old documentation/docs/benchmarks.md path instead of documentation/en/src/benchmarks.md.
The build.sh already performs sed substitution of {{VERSION}} with the
actual version from Cargo.toml, but index.md had a hardcoded "3.2.4"
instead of the template placeholder.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR refactors the documentation and configuration generation system, migrates from mkdocs-material to mdBook, and rewrites the README with a research-backed comparison table.
Data-driven config & docs generation
fields.yamlas single source of truth for all configuration field descriptions (config comments + reference docs)generate-docssubcommand produces reference documentation (Markdown) fromfields.yamlgenerate --referenceproduces a complete annotated config without requiring a PostgreSQL connectiongenerate --format yaml|tomlwith auto-detection from file extensiongenerate --russian-comments(--ru) for Russian inline comments in generated configspubconfig field appears infields.yamlDocumentation migration: mkdocs-material → mdBook
mdbook-admonishformat--ruconfig generation)documentation/build.shbuilds the site; CI updated accordinglyREADME rewrite
server_passwordgotcha (the add simple systemd config #1 setup issue)patroni_proxysection with Mermaid architecture diagramDeleted
mkdocs.yml,pyproject.toml,uv.lock,mkdocs-customizations/documentation/docs/reference/(now generated at build time intodocumentation/en/src/reference/)