From 6e125797ad457a245ffd04e43249293d54d95891 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sat, 17 Oct 2026 21:36:37 +0300 Subject: [PATCH] docs: drop dashes and bold labels from the site, profile and repo docs --- AGENTS.md | 10 +++++----- CONTEXT.md | 24 ++++++++++++------------ CONTRIBUTING.md | 10 +++++----- README.md | 12 ++++++------ brand/README.md | 14 +++++++------- docs/index.md | 36 ++++++++++++++++++------------------ profile/README.md | 4 ++-- 7 files changed, 55 insertions(+), 55 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9b4ff19..becb7c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,11 +1,11 @@ # modern-python/.github -[`CONTEXT.md`](CONTEXT.md) says what this repo is and owns the vocabulary — read it +[`CONTEXT.md`](CONTEXT.md) says what this repo is and owns the vocabulary. Read it before naming a mark, a colourway, or a surface. ## Naming & branding -- Brand/framework casing — use exactly: `modern-di`, `that-depends`, `Litestar` +- Brand/framework casing: use exactly `modern-di`, `that-depends`, `Litestar` (not "LiteStar"), `FastStream`, `FastAPI`, `Typer`, `SQLAlchemy`, `PostgreSQL`. - Per-project docs sites live at `.modern-python.org` (only some repos have one). @@ -18,9 +18,9 @@ The org profile's `coverage 100%` badge is static and deliberately unlinked: the org-level coverage URL to point at, and the gate in [TS2](https://modern-python.org/standard/#TS2) is what makes the claim true. -A repo may be listed on the org profile **before** its package reaches PyPI. Its +A repo may be listed on the org profile before its package reaches PyPI. Its Downloads badge 404s until pepy indexes it; the Stars badge and repo link resolve -meanwhile. That lag is self-healing — note it, never block the listing on it. +meanwhile. That lag is self-healing: note it, but never block the listing on it. ## Brand surfaces @@ -32,7 +32,7 @@ home page from `site_name`, so `title:` renders as ` - `. ## CI gotcha -GitHub occasionally type-checks a **stale `refs/pull//merge`** after a push, so a +GitHub occasionally type-checks a stale `refs/pull//merge` after a push, so a PR can show an old lint/test failure that no longer matches the branch. Confirm by running the failing check locally at the branch HEAD (with the pinned tool version); if it's clean, push a fresh commit to force GitHub to recompute the merge ref. diff --git a/CONTEXT.md b/CONTEXT.md index 918a642..9448658 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,7 +1,7 @@ # modern-python/.github The org's shared repo: it generates the brand kit under `brand/`, builds the org -site at **modern-python.org** from `docs/` (MkDocs Material), and hosts the org +site at modern-python.org from `docs/` (MkDocs Material), and hosts the org profile shown on the GitHub org page (`profile/README.md`) plus the community health files every other repo inherits. @@ -15,36 +15,36 @@ heavily this repo uses it. A square logo drawn from vector geometry, with no type. The *org mark* is the interlocked-snakes pinwheel with a chevron; a *project mark* is the green+gold snake frame around one repo's inner symbol. -_Avoid_: logo — for our own assets. A third party's logo is a logo (`symbols.py` draws from +_Avoid_: logo, for our own assets. A third party's logo is a logo (`symbols.py` draws from Flask's and FastStream's), and `icon` is the right word for a favicon or the `icon()` full-bleed square. **Inner symbol**: The gold shape inside a project mark's frame, one per repo, chosen in `projects.py::MANIFEST`. It is the only thing that distinguishes one project mark from another. -_Avoid_: glyph — which `text.py` needs for its real meaning, an outlined character from the font. +_Avoid_: glyph, which `text.py` needs for its real meaning: an outlined character from the font. **Wordmark**: The `MODERN`/`PYTHON` crop-mark type, outlined to paths. Type only, no mark. **Lockup**: -A mark and a name composed into one fixed arrangement — the org wordmark, or a project's +A mark and a name composed into one fixed arrangement: the org wordmark, or a project's mark-plus-repo-name banner. Named in the files themselves: `lockup-light.svg`, `lockup-dark.svg`. **Colourway**: One named ink pair an asset renders in: *light* is green-ink + gold-light, *dark* is cream + gold-dark. Every asset ships both, and which one a surface loads is a `prefers-color-scheme` or `data-md-color-scheme` swap, never a separate design. -_Avoid_: colorway — the repo has spelled it both ways; British spelling wins for this one word, +_Avoid_: colorway. The repo has spelled it both ways; British spelling wins for this one word, because the assets and the docs that describe them already read `colour`. **Knockout**: -Cream painted **on top of** a gold shape to cut a hole in it. Cream is never ink in its own right: +Cream painted on top of a gold shape to cut a hole in it. Cream is never ink in its own right: on a transparent background it is invisible on light surfaces and stray white on dark ones. **Org profile**: `profile/README.md`, the landing page GitHub renders at github.com/modern-python. Distinct from the -**org site**, `modern-python.org`, built from `docs/` — the two carry different content and drift +org site, `modern-python.org`, built from `docs/`. The two carry different content and drift apart if the names are used loosely. **Owned channel**: @@ -56,18 +56,18 @@ profile and the site. **Borrowed audience**: A venue someone else runs, where the org participates as a guest and never moderates: the Python Discord, the framework community channels, Stack Overflow, the newsletters. -_Avoid_: channel — a borrowed audience is never one of ours, and calling it one invites the +_Avoid_: channel. A borrowed audience is never one of ours, and calling it one invites the assumption that we moderate it. **Standard**: The written, normative description of what makes a repo a modern-python repo, owned by this repo and published on the org site. A repo either meets it, or carries an exemption. -_Avoid_: guidelines, conventions, rules — each reads as advisory, and the standard is not. +_Avoid_: guidelines, conventions, rules. Each reads as advisory, and the standard is not. **Requirement**: One numbered statement of the standard, cited by its stable ID (`CI6`). A MUST or MUST NOT requirement is core; a SHOULD is a recommendation; a MAY is a permission. -_Avoid_: rule, check — a check is what verifies a requirement, not the requirement. +_Avoid_: rule, check. A check is what verifies a requirement, not the requirement. **Core**: The standard's MUST and MUST NOT requirements, which a repo must meet. Everything outside the core @@ -76,5 +76,5 @@ _Avoid_: baseline, required set **Exemption**: A recorded, reasoned deviation of one repo from one or more core requirements. -_Avoid_: exception, override — both already mean something in the DI repos; deviation, drift — a -deviation nobody recorded is drift, not an exemption. +_Avoid_: exception, override (both already mean something in the DI repos); deviation, drift (a +deviation nobody recorded is drift, not an exemption). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c54d5d3..8915120 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,10 +6,10 @@ unless a repository overrides them with its own `CONTRIBUTING.md`. ## Ways to contribute -- **Report bugs** and **request features** via the issue templates. -- **Ask questions** in [GitHub Discussions](https://github.com/orgs/modern-python/discussions). -- **Improve docs** — typo fixes and clarifications are very welcome. -- **Send pull requests** — see the workflow below. +- Report bugs and request features via the issue templates. +- Ask questions in [GitHub Discussions](https://github.com/orgs/modern-python/discussions). +- Improve the docs. Typo fixes and clarifications are very welcome. +- Send pull requests, following the workflow below. ## Development setup @@ -27,7 +27,7 @@ just --list # see available tasks (lint, test, etc.) ## Pull request workflow 1. Fork the repository and create a topic branch from `main`. -2. Make your change. Keep it focused — one logical change per PR. +2. Make your change. Keep it focused: one logical change per PR. 3. Run lint, type check, and tests locally before pushing: ```bash just lint-ci # read-only lint, format, and type checks diff --git a/README.md b/README.md index 869fcca..fb0e41e 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,12 @@ Organization-level configuration and the public website for the [Modern Python](https://github.com/modern-python) GitHub organization. -- **Website:** [modern-python.org](https://modern-python.org) — built from `docs/` - with MkDocs + Material and deployed to GitHub Pages via - [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) on every push to `main`. -- **Org profile:** [`profile/README.md`](profile/README.md) renders on the - organization's GitHub landing page. -- **Deployment & domain setup:** see [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). +The website, [modern-python.org](https://modern-python.org), is built from `docs/` +with MkDocs + Material and deployed to GitHub Pages via +[`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) on every push to `main`. +The org profile, [`profile/README.md`](profile/README.md), renders on the +organization's GitHub landing page. Deployment and domain setup are covered in +[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). ## Local development diff --git a/brand/README.md b/brand/README.md index 0bd22df..dbdb634 100644 --- a/brand/README.md +++ b/brand/README.md @@ -1,6 +1,6 @@ # modern-python brand kit -Source of truth for the org's **favicon** and **social card**. Generated assets +Source of truth for the org's favicon and social card. Generated assets live in `brand/org/`. Regenerate with: ```bash @@ -23,10 +23,10 @@ Without it the SVGs are still written and PNGs are skipped. ## Mark Two "snakes" (corner brackets with square heads and diagonal-cut tails), one -ink and one gold, in opposite corners. The **icon** frames a gold chevron -between them (favicon, avatar, and the site header logo). The **wordmark -lockup** pulls them into crop marks framing `MODERN` / `PYTHON` set in **Jost** -(SIL OFL, outlined to paths at build time — see `brand/build/fonts/Jost-OFL.txt`). +ink and one gold, in opposite corners. The icon frames a gold chevron +between them (favicon, avatar, and the site header logo). The wordmark +lockup pulls them into crop marks framing `MODERN` / `PYTHON` set in Jost +(SIL OFL, outlined to paths at build time; see `brand/build/fonts/Jost-OFL.txt`). ## Outputs (`brand/org/`) @@ -45,7 +45,7 @@ Each repo gets a large-format mark: the constant green+gold snake-frame with one gold inner symbol (see `brand/build/projects.py::MANIFEST`). Regenerate with `uv run python -m brand.build.render`; outputs land in `brand/projects//` as `mark.svg`, three lockup files (see below), and -PNGs. These are large-format only — every repo's favicon/avatar stays the org mark. +PNGs. These are large-format only; every repo's favicon/avatar stays the org mark. ### Lockup outputs @@ -67,7 +67,7 @@ and docs URL on cream. The docs-site repos are listed in centered hero on their `docs/index.md`, vendored into the repo's `docs/assets/`. PNGs are palette-quantized at build time (`brand/build/raster.py`, Pillow -FASTOCTREE) — indexed-colour, with no visible change (the art is flat-colour). +FASTOCTREE) to indexed colour, with no visible change because the art is flat-colour. The large assets (social cards, 1024px marks) shrink ~70–80% vs raw `rsvg-convert` output; the tiny favicons less. Regenerate with `uv run python -m brand.build.render`. diff --git a/docs/index.md b/docs/index.md index 159388c..95651f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ hide: Open-source templates and libraries for building production-ready Python -applications — web services, microservices, and the dependency injection that +applications: web services, microservices, and the dependency injection that wires them together. @@ -57,31 +57,31 @@ wires them together. ## The stack { #stack } The modern-python projects fit together into one coherent stack for building -production Python services. Use one piece or all of them — each is independent. +production Python services. Each project is independent, so use one piece or all of them. -- **Start from a template.** +- Start from a template. [`fastapi-sqlalchemy-template`](https://github.com/modern-python/fastapi-sqlalchemy-template) and [`litestar-sqlalchemy-template`](https://github.com/modern-python/litestar-sqlalchemy-template) - give you a dockerized, batteries-included app — FastAPI or Litestar, - SQLAlchemy 2, PostgreSQL, with dependency injection already wired. -- **Wire your dependencies** with - [`modern-di`](https://github.com/modern-python/modern-di) — typed, scoped + give you a dockerized, batteries-included app on FastAPI or Litestar, + SQLAlchemy 2 and PostgreSQL, with dependency injection already wired. +- Wire your dependencies with + [`modern-di`](https://github.com/modern-python/modern-di): typed, scoped dependency injection with one wiring shared across web frameworks (FastAPI, Litestar, Starlette, Flask, aiohttp), task queues (Celery, arq, taskiq), RPC and messaging (gRPC, FastStream, aiogram), and CLIs (Typer). ([`that-depends`](https://github.com/modern-python/that-depends), the older DI framework, is still maintained.) -- **Call other services reliably** with - [`httpware`](https://github.com/modern-python/httpware) — an httpx-based client +- Call other services reliably with + [`httpware`](https://github.com/modern-python/httpware), an httpx-based client with typed errors, typed response bodies, and a composable resilience chain (retry, bulkhead, circuit breaker). -- **Publish events reliably** with - [`faststream-outbox`](https://github.com/modern-python/faststream-outbox) — the - transactional outbox pattern for FastStream + PostgreSQL: write your domain row - and outbox row in one transaction, relay to any broker with one decorator. -- **Instrument everything** with - [`lite-bootstrap`](https://github.com/modern-python/lite-bootstrap) — - OpenTelemetry, Prometheus, Sentry, and structlog wired into FastAPI, Litestar, +- Publish events reliably with + [`faststream-outbox`](https://github.com/modern-python/faststream-outbox), the + transactional outbox pattern for FastStream + PostgreSQL. You write your domain + row and outbox row in one transaction and relay to any broker with one decorator. +- Instrument everything with + [`lite-bootstrap`](https://github.com/modern-python/lite-bootstrap), which wires + OpenTelemetry, Prometheus, Sentry, and structlog into FastAPI, Litestar, or FastStream in a few lines. Every project is built with the same tooling @@ -98,8 +98,8 @@ Every project is built with the same tooling !!! tip "Which one should I use?" - Start new projects on [`modern-di`](https://github.com/modern-python/modern-di) - — a minimal core plus framework integrations, listed in + Start new projects on [`modern-di`](https://github.com/modern-python/modern-di). + It has a minimal core plus framework integrations, listed in [its docs](https://modern-di.modern-python.org/). [`that-depends`](https://github.com/modern-python/that-depends) is the earlier, diff --git a/profile/README.md b/profile/README.md index 82eb42a..f4f376a 100644 --- a/profile/README.md +++ b/profile/README.md @@ -5,7 +5,7 @@

-Open-source templates and libraries for building production-ready Python applications — web services, microservices, and the dependency injection that wires them together. +Open-source templates and libraries for building production-ready Python applications: web services, microservices, and the dependency injection that wires them together. [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) @@ -21,7 +21,7 @@ Open-source templates and libraries for building production-ready Python applica ### Dependency injection -**Which one?** Start new projects on [`modern-di`](https://github.com/modern-python/modern-di) — a minimal core plus framework integrations, listed in [its docs](https://modern-di.modern-python.org/). +Start new projects on [`modern-di`](https://github.com/modern-python/modern-di). It has a minimal core plus framework integrations, listed in [its docs](https://modern-di.modern-python.org/). [`that-depends`](https://github.com/modern-python/that-depends) is the earlier, async-first sibling and stays maintained. `modern-di` has migration guides [from `that-depends`](https://modern-di.modern-python.org/migration/from-that-depends/) and [from `dependency-injector`](https://modern-di.modern-python.org/migration/from-dependency-injector/).