docs: reword README; begin splitting off API and plugin documents
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I832845f6ca2a8ac484b55ebab957a0b16a6a6964
This commit is contained in:
parent
8e33088458
commit
3a9d55eb2c
GPG key ID:
29D95B64378DB4BF
1 changed files with 34 additions and 28 deletions
|
|
@ -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
|
||||
|
||||
<!-- markdownlint-disable MD013-->
|
||||
|
||||
|
|
@ -172,7 +193,7 @@ Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`,
|
|||
|
||||
<!-- markdownlint-enable MD013-->
|
||||
|
||||
### 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
|
||||
|
||||
<!-- markdownlint-disable MD013-->
|
||||
|
||||
|
|
@ -198,28 +219,13 @@ query when listing members, returning results dynamically.
|
|||
|
||||
<!-- markdownlint-enable MD013-->
|
||||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue