Docs: a page for each topic, and an API reference laid out like docs.rs #223

New Issue

rays · 2026-10-13T06:55:36-07:00

rays commented

2026-10-13 06:55:36 -07:00

ipxreader.app/docs is one long page. Split it: install, the command line, and the directory each on a page of its own, and an API reference for ipx and the directory laid out the way docs.rs lays out a crate: a sidebar of items, a page for each endpoint with its signature, parameters, what it returns and its errors, and a page for each type it returns, with its fields.

73 KiB

69 KiB

151 KiB

134 KiB

110 KiB

endpoint-phone.png

60 KiB

rays added the enhancement label 2026-10-13 06:55:36 -07:00

rays referenced this issue from a commit

2026-10-13 07:03:04 -07:00

Docs: a page each, and API references for ipx and the directory laid out like docs.rs (#223)

rays commented

2026-10-13 07:03:48 -07:00

A prototype, on the branch docs-pages and deployed only to the preview at https://docs-pages.ipxreader.pages.dev/docs/ (ipxreader.app is unchanged). For your approval before it is merged and deployed.

Before: one long page.

After: guides a page each (Overview, Install, Command line, Directory), and an API reference for ipx and one for the directory, as docs.rs lays out a crate: a root page listing modules and types, a page a module, a page an endpoint (its declaration, parameters, body, returns, errors, an example) and a page a type (its fields, and which endpoints use it). 128 pages, generated by site/gen.mjs from site/api.mjs.

+-------------+---------------------------------------------+
| ipx 1.0.0   | ipx::entries                                |
|             | Endpoint ipx::entries::get_feed_entries  Src|
| MODULE      | +-----------------------------------------+ |
|  entries    | | GET /api/feeds/{id}/entries             | |
| GET  get_.. | |     query  Page                         | |
| POST post.. | |     ->     EntryPage                    | |
| MODULES     | +-----------------------------------------+ |
|  auth ...   | Path parameters / Query / Returns / Errors  |
| TYPES       | Example                                     |
|  FeedRow .. |                                             |
+-------------+---------------------------------------------+

Overview:

The ipx reference's root:

An endpoint:

A type:

An endpoint on a phone (the sidebar follows the page there):

Yours to decide:

The paths read like Rust (ipx::entries::get_feed_entries) and the types are written as Rust writes them (Option<String>, Vec<EntryRow>), to match docs.rs. Plain JSON names (string or null) would read better to someone who does not write Rust.
The admin endpoints are documented alongside the rest, in a module of their own. The Caddy-only ones (page-check, login-check, signin), /api/client and /api/art are left out as the page's own business.
No search box: the site's Content-Security-Policy allows no script of its own. One could be added with a script of its own and the policy widened for it.

A prototype, on the branch `docs-pages` and deployed only to the preview at https://docs-pages.ipxreader.pages.dev/docs/ (ipxreader.app is unchanged). For your approval before it is merged and deployed. **Before:** one long page. ![before](https://git.sdf1.net/attachments/95e8d7b9-bf22-4f60-a37c-7676f0fff854) **After:** guides a page each (Overview, Install, Command line, Directory), and an API reference for ipx and one for the directory, as docs.rs lays out a crate: a root page listing modules and types, a page a module, a page an endpoint (its declaration, parameters, body, returns, errors, an example) and a page a type (its fields, and which endpoints use it). 128 pages, generated by `site/gen.mjs` from `site/api.mjs`. ``` +-------------+---------------------------------------------+ | ipx 1.0.0 | ipx::entries | | | Endpoint ipx::entries::get_feed_entries Src| | MODULE | +-----------------------------------------+ | | entries | | GET /api/feeds/{id}/entries | | | GET get_.. | | query Page | | | POST post.. | | -> EntryPage | | | MODULES | +-----------------------------------------+ | | auth ... | Path parameters / Query / Returns / Errors | | TYPES | Example | | FeedRow .. | | +-------------+---------------------------------------------+ ``` Overview: ![overview](https://git.sdf1.net/attachments/c76f3852-e096-4f9d-9102-0dda56da7aa4) The ipx reference's root: ![ipx root](https://git.sdf1.net/attachments/7fe3ca34-6117-48b3-82ce-77b1bdb7bba6) An endpoint: ![endpoint](https://git.sdf1.net/attachments/27e8b029-5b73-42ce-a6f4-ed4f92725ea7) A type: ![type](https://git.sdf1.net/attachments/6c6ed8d3-3448-4ca6-9462-214de6d59844) An endpoint on a phone (the sidebar follows the page there): ![endpoint on a phone](https://git.sdf1.net/attachments/3a46e5a3-6407-4339-8843-0f812ea78e86) Yours to decide: * The paths read like Rust (`ipx::entries::get_feed_entries`) and the types are written as Rust writes them (`Option<String>`, `Vec<EntryRow>`), to match docs.rs. Plain JSON names (`string or null`) would read better to someone who does not write Rust. * The admin endpoints are documented alongside the rest, in a module of their own. The Caddy-only ones (`page-check`, `login-check`, `signin`), `/api/client` and `/api/art` are left out as the page's own business. * No search box: the site's Content-Security-Policy allows no script of its own. One could be added with a script of its own and the policy widened for it.

rays commented

2026-10-13 08:48:32 -07:00

Merged to main in e4b5055 and deployed to ipxreader.app: guides at /docs/, API references at /docs/api/ipx/ and /docs/api/directory/.

Merged to main in e4b5055 and deployed to ipxreader.app: guides at /docs/, API references at /docs/api/ipx/ and /docs/api/directory/.

rays closed this issue

2026-10-13 08:48:32 -07:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rays/ipx#223