From 0a7e114681a45c1473c92a5865dfc97c6bbc80e0 Mon Sep 17 00:00:00 2001 From: splitsec2 <35583321+splitsec2@users.noreply.github.com> Date: Sat, 31 Oct 2026 03:52:01 -0600 Subject: [PATCH] docs(dev): new routes go in a register__routes module (#1622) Nothing in the developer docs says where a new route goes, so the next contributor adds it to `main.py` again. This writes down the convention from Discussion #1536: a new route group gets its own `register__routes` module under `shelfmark/core/`, and `main.py` calls it once. It is one paragraph on a new page, `docs/dev/routes.md`, with a line in the developer index. It also says that a few older routes are still in `main.py` and are being moved out one group at a time. The route moves in that discussion will follow what this says, so this goes first. --- docs/dev/index.md | 1 + docs/dev/routes.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 docs/dev/routes.md diff --git a/docs/dev/index.md b/docs/dev/index.md index f00c7632..7141a820 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -4,4 +4,5 @@ Guides for adding to Shelfmark. - [Release Sources Plugin Guide](release-sources-plugin-guide.md): add a source that searches for releases and a handler that downloads them - [Plugin Settings Guide](plugin-settings.md): add settings tabs and fields for a plugin to the Settings UI +- [Adding Routes](routes.md): where a new API route goes, and how a route module gets what it needs - [Metadata Providers](../../shelfmark/metadata_providers/README.md): add a metadata provider diff --git a/docs/dev/routes.md b/docs/dev/routes.md new file mode 100644 index 00000000..0b02337d --- /dev/null +++ b/docs/dev/routes.md @@ -0,0 +1,3 @@ +# Adding Routes + +New API routes go in their own module under `shelfmark/core/`, named for the group (`stats_routes.py`, `settings_routes.py`), as a `register__routes(app, ...)` function that `main.py` calls once. Anything the routes need that lives in `main.py` or is shared with another group, such as `login_required`, the auth mode or the user database, is passed in as a parameter, so a route module never imports `main`. When a test patches one of those, pass a callable that is evaluated per request, the way `register_stats_routes` does. Helpers that belong to one group stay in its module. Please don't add `@app.route` handlers to `main.py` itself: two PRs that each add a route there land in the same stretch of the file and conflict, where two route modules only share the one register call. `shelfmark/core/stats_routes.py` is the smallest example to copy. A few older routes are still in `main.py` and are being moved out one group at a time, see [Discussion #1536](https://github.com/calibrain/shelfmark/discussions/1536).