From ab4d763304a9696c90e496f32052a9bd26c7460a Mon Sep 17 00:00:00 2001 From: Lennart <18233294+lennart-k@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:39:23 +0200 Subject: [PATCH] tiny improvements to documentation --- .editorconfig | 2 ++ docs/developers/frontend.md | 7 ++++ docs/developers/rfcs.md | 8 ++--- docs/index.md | 8 ++--- docs/installation/configuration.md | 31 ++++++++++++++++++ .../index.md} | 32 ------------------- docs/style.css | 10 ++++++ mkdocs.yml | 14 ++++++-- 8 files changed, 70 insertions(+), 42 deletions(-) create mode 100644 docs/developers/frontend.md create mode 100644 docs/installation/configuration.md rename docs/{installation.md => installation/index.md} (68%) create mode 100644 docs/style.css diff --git a/.editorconfig b/.editorconfig index 01daba7..69efb10 100644 --- a/.editorconfig +++ b/.editorconfig @@ -2,3 +2,5 @@ indent_style = space indent_size = 4 +[docs/**/*.md] +indent_size = 4 diff --git a/docs/developers/frontend.md b/docs/developers/frontend.md new file mode 100644 index 0000000..b280e80 --- /dev/null +++ b/docs/developers/frontend.md @@ -0,0 +1,7 @@ +# Frontend + +The frontend is currently generated through [askama templates](https://askama.readthedocs.io/en/stable/) for server-side rendered pages +and uses Web Components for interactive elements. + +Normally, content that will be statically served by the frontend module (i.e. stylesheet and web components) is embedded into the binary. +Using the `frontend-dev` feature you can serve it from source to see changes without recompiling RustiCal. diff --git a/docs/developers/rfcs.md b/docs/developers/rfcs.md index 8b3e6ba..df4efb7 100644 --- a/docs/developers/rfcs.md +++ b/docs/developers/rfcs.md @@ -3,11 +3,11 @@ Collection of RFCs relevant to this project - Versioning Extensions to WebDAV: [RFC 3253](https://datatracker.ietf.org/doc/html/rfc3253) - - provides the REPORT method + - provides the REPORT method - Calendaring Extensions to WebDAV (CalDAV): [RFC 4791](https://datatracker.ietf.org/doc/html/rfc4791) - Scheduling Extensions to CalDAV: [RFC 6638](https://datatracker.ietf.org/doc/html/rfc6638) - - not sur`e yet whether to implement this + - not sure yet whether to implement this - Collection Synchronization WebDAV [RFC 6578](https://datatracker.ietf.org/doc/html/rfc6578) - - We need to implement sync-token, etc. - - This is important for more efficient synchronisation + - We need to implement sync-token, etc. + - This is important for more efficient synchronisation - iCalendar [RFC 2445](https://datatracker.ietf.org/doc/html/rfc2445#section-3.10) diff --git a/docs/index.md b/docs/index.md index de2b334..7c4b1e1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,10 +3,10 @@ a CalDAV/CardDAV server !!! warning -RustiCal is **not production-ready!** -I've been using it for the last few weeks and I'm slowly becoming more confident, -however you'd be one of the first testers so expect bugs and rough edges. -If you still want to play around with it in its current state, absolutely feel free to do so and to open up an issue if something is not working. :) + RustiCal is **not production-ready!** + I've been using it for the last few weeks and I'm slowly becoming more confident, + however you'd be one of the first testers so expect bugs and rough edges. + If you still want to play around with it in its current state, absolutely feel free to do so and to open up an issue if something is not working. :) ## Features diff --git a/docs/installation/configuration.md b/docs/installation/configuration.md new file mode 100644 index 0000000..016c9b2 --- /dev/null +++ b/docs/installation/configuration.md @@ -0,0 +1,31 @@ +# Configuration + +While RustiCal (apart from user management) will work without any configuration you should still know how to configure it. :) + +You can either mount a `config.toml` file or use environment variables (recommended). + +To see the options you can generate a default configuration using + +```sh title="Generate default config.toml" +rustical gen-config +``` + +To see all configuration options available you can browse the [Cargo docs](/rustical/_crate/rustical/config/struct.Config.html). + +## Environment variables + +The options in `config.toml` can also be configured using environment variables. +Names translate the following: + +```toml title="Example config.toml" +[data_store.toml] +path = "asd" +``` + +becomes `RUSTICAL_DATA_STORE__TOML__PATH`. +Every variable is + +- uppercase +- prefixed by `RUSTICAL_` +- Dots become `__` +- Arrays are JSON-encoded diff --git a/docs/installation.md b/docs/installation/index.md similarity index 68% rename from docs/installation.md rename to docs/installation/index.md index 3752e9e..0e55a5b 100644 --- a/docs/installation.md +++ b/docs/installation/index.md @@ -40,38 +40,6 @@ App tokens are used by your CalDAV/CardDAV client (which can be managed through I recommend to generate random app tokens for each CalDAV/CardDAV client. Since the app tokens are random they use the faster `pbkdf2` algorithm. -## Configuration - -While RustiCal (apart from user management) will work without any configuration you should still know how to configure it. :) - -You can either mount a `config.toml` file or use environment variables. - -To see the options you can generate a default configuration using - -```sh title="Generate default config.toml" -rustical gen-config -``` - -To see all configuration options available you can browse the [Cargo docs](/rustical/_crate/rustical/config/struct.Config.html). - -### Environment variables - -The options in `config.toml` can also be configured using environment variables. -Names translate the following: - -```toml title="Example config.toml" -[data_store.toml] -path = "asd" -``` - -becomes `RUSTICAL_DATA_STORE__TOML__PATH`. -Every variable is - -- uppercase -- prefixed by `RUSTICAL_` -- Dots become `__` -- Arrays are JSON-encoded - ## Manual ```sh diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..df03a30 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,10 @@ +body .md-main { + h1 { + font-weight: bold; + color: var(--md-typeset-color); + } +} + +.md-tabs { + box-shadow: 0px 0 20px -10px black; +} diff --git a/mkdocs.yml b/mkdocs.yml index 0bb4c2b..b20681e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,7 +14,7 @@ theme: name: Switch to light mode - media: "(prefers-color-scheme: light)" scheme: default - primary: indigo + primary: white accent: indigo toggle: icon: material/toggle-switch @@ -38,6 +38,13 @@ theme: - content.tooltips - navigation.indices - navigation.tabs + - navigation.indexes + - navigation.indexes + - navigation.instant + - navigation.footer + +extra_css: + - style.css markdown_extensions: - fenced_code @@ -58,10 +65,13 @@ markdown_extensions: nav: - Home: index.md - - Installation: installation.md + - Installation: + - installation/index.md + - Configuration: installation/configuration.md - OpenID Connect: setup/oidc.md - Developers: - developers/index.md - Relevant RFCs: developers/rfcs.md + - Frontend: developers/frontend.md - Debugging: developers/debugging.md - Cargo docs: /rustical/_crate/rustical/