diff --git a/docs/README.md b/docs/README.md index 0b8f72f..595e2af 100644 --- a/docs/README.md +++ b/docs/README.md @@ -130,12 +130,33 @@ $ cargo run -p pinakes-ui > bound to port 3000. Set `PINAKES_SERVER_URL` to point at the server if it is > not on `localhost:3000`. -## API +### Extending Pinakes + +[Server API documentation]: ./api.md +[Plugin API documentation]: ./plugins.md + +While Pinakes _does_ aim to be as comprehensive as humanly possible, it is not +feasible to maintain all features in one gigantic repository without taking on +an immense technical debt. To avoid this kind of resource mismanagement while +still allowing for _all_ kinds of extension, Pinakes features two features at +your convenience: + +- Server API Routes +- Plugin API + +### API There exists a comprehensive UI for the server component that you may query directly from the `/api/v1` endpoint. All other endpoints are under `/api/v1`. -### Media +The server API is, of course, a part of Pinakes core design but it is also how +first-party interfaces like `pinakes-ui` and `pinakes-tui` interact with the +server. You may write your own interfaces for a running Pinakes server with +minimal effort by simply sending requests to the API through your preferred +means. See [Server API documentation] on available routes and tips on how to +interact with the API. + +#### Media | Method | Path | Description | | -------- | -------------------- | ------------------------------------- | @@ -147,7 +168,7 @@ directly from the `/api/v1` endpoint. All other endpoints are under `/api/v1`. | `GET` | `/media/{id}/stream` | Stream file content | | `POST` | `/media/{id}/open` | Open with system viewer | -### Search +#### Search | Method | Path | Description | | ------ | --------------- | ---------------------------------------------- | @@ -156,7 +177,7 @@ directly from the `/api/v1` endpoint. All other endpoints are under `/api/v1`. Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`, `prefix*`, `fuzzy~`, `-excluded`, `a b` (AND), `a OR b`, `(grouped)`. -### Tags +#### Tags @@ -172,7 +193,7 @@ Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`, -### Collections +#### Collections | Method | Path | Description | | -------- | ---------------------------------- | ----------------- | @@ -187,7 +208,7 @@ Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`, Virtual collections (kind `"virtual"`) evaluate their `filter_query` as a search query when listing members, returning results dynamically. -### Audit & Scanning +#### Audit & Scanning @@ -198,28 +219,13 @@ query when listing members, returning results dynamically. -## Testing - -```sh -# Unit and integration tests for the core library (SQLite in-memory) -cargo test -p pinakes-core - -# API integration tests for the server -cargo test -p pinakes-server -``` - -## Supported Media Types - -| Category | Formats | -| -------- | ------------------------------- | -| Audio | MP3, FLAC, OGG, WAV, AAC, Opus | -| Video | MP4, MKV, AVI, WebM | -| Document | PDF, EPUB, DjVu | -| Text | Markdown, Plain text | -| Image | JPEG, PNG, GIF, WebP, SVG, AVIF | - -Metadata extraction uses lofty (audio, MP4), matroska (MKV), lopdf (PDF), epub -(EPUB), and gray_matter (Markdown frontmatter). +The other method, which is by far the most powerful but also perhaps the least +polished as of writing is the **plugin system**. This is designed as a means of +implementing various user-facing features to Pinakes _server_ by writing your +own plugins that can modify certain elements. While this system is not as stable +as the server API, it is generally in good shape and example plugins are +provided. Please see the [Plugin API documentation] for more details, examples +and design. ## Storage Backends