NotAShelf/pinakes
1
0
Fork 0
Code Issues 6 Pull requests Projects Releases Packages Wiki Activity Actions

docs: reword README; begin splitting off API and plugin documents

Browse source 
Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I832845f6ca2a8ac484b55ebab957a0b16a6a6964
This commit is contained in:
raf 2026-02-10 11:53:48 +03:00
commit 3a9d55eb2c
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF
1 changed files with 34 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

62
docs/README.md
View file

@ -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 > bound to port 3000. Set `PINAKES_SERVER_URL` to point at the server if it is
> not on `localhost:3000`. > 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 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`. 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 | | 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 | | `GET` | `/media/{id}/stream` | Stream file content |
| `POST` | `/media/{id}/open` | Open with system viewer | | `POST` | `/media/{id}/open` | Open with system viewer |
### Search #### Search
| Method | Path | Description | | 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`, Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`,
`prefix*`, `fuzzy~`, `-excluded`, `a b` (AND), `a OR b`, `(grouped)`. `prefix*`, `fuzzy~`, `-excluded`, `a b` (AND), `a OR b`, `(grouped)`.
### Tags #### Tags
<!-- markdownlint-disable MD013--> <!-- markdownlint-disable MD013-->
@ -172,7 +193,7 @@ Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`,
<!-- markdownlint-enable MD013--> <!-- markdownlint-enable MD013-->
### Collections #### Collections
| Method | Path | Description | | 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 Virtual collections (kind `"virtual"`) evaluate their `filter_query` as a search
query when listing members, returning results dynamically. query when listing members, returning results dynamically.
### Audit & Scanning #### Audit & Scanning
<!-- markdownlint-disable MD013--> <!-- markdownlint-disable MD013-->
@ -198,28 +219,13 @@ query when listing members, returning results dynamically.
<!-- markdownlint-enable MD013--> <!-- markdownlint-enable MD013-->
## Testing 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
```sh implementing various user-facing features to Pinakes _server_ by writing your
# Unit and integration tests for the core library (SQLite in-memory) own plugins that can modify certain elements. While this system is not as stable
cargo test -p pinakes-core 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
# API integration tests for the server and design.
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).
## Storage Backends ## Storage Backends