docs: add autogenerated documentation site

.github/workflows/docs.yaml

@@ -0,0 +1,78 @@
+on:
+  push:
+    branches: [main, docs]
+
+name: Build documentation site
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: swatinem/rust-cache@v2
+        with:
+          workspaces: |
+            mm-protocol
+            mm-client-common
+
+      - name: install protoc
+        run: |
+          sudo apt update
+          sudo apt install protobuf-compiler
+
+      - name: install zola
+        uses: taiki-e/install-action@v2
+        with:
+          tool: [email protected]
+
+      - name: generate config reference
+        run: |
+          mkdir -p docs/content/reference
+          cargo run --manifest-path mm-docgen/Cargo.toml --bin config-docgen \
+            mmserver.default.toml > docs/content/reference/config.md
+
+      - name: generate protocol reference
+        run: |
+          cargo run --manifest-path mm-docgen/Cargo.toml --bin protocol-docgen \
+            mm-protocol/src/messages.proto > docs/content/reference/protocol.md
+
+      - name: zola build
+        run: zola -r docs build -o docs/build
+
+      - name: generate rustdoc for mm-protocol
+        run: |
+          cargo doc --manifest-path mm-protocol/Cargo.toml \
+            --no-deps --target-dir docs/build
+
+      - name: generate rustdoc for mm-client-common
+        run: |
+          cargo doc --manifest-path mm-client-common/Cargo.toml \
+            --no-deps --target-dir docs/build
+
+      - name: Upload static files
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+
+
+

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/themes/anemone"]
+	path = docs/themes/anemone
+	url = https://github.com/Speyll/anemone

README.md

@@ -17,56 +17,8 @@ This is a game streaming and remote desktop tool for Linux, featuring:
 > [!WARNING]
 > Alpha software! Please submit any issues you encounter. Run the server with `--bug-report` to generate detailed logs and record videos to attach to your report.
 
-### Quickstart
+### Quick Links
 
-Grab the latest release (link above), and run it on a server with a GPU:
+ - [Documentation](https://colinmarc.github.io/magic-mirror)
+ - [macOS Client](https://github.com/colinmarc/magic-mirror-swiftui/releases/latest)
 
-```shell
-$ cat > steam-bigpicture.toml <<EOF
-command = ["steam", "-gamepadui"]
-xwayland = true
-EOF
-$ ./mmserver --bind "<your local ip>:9599" -i steam-bigpicture.toml
-```
-
-You can replace steam with your app of choice, or even a full nested desktop environment like [Sway](https://swaywm.org/).
-
-And then on the client (after installing `ffmpeg`):
-
-```shell
-$ ./mmclient "<ip>:9599" steam-bigpicture --codec h265 --resolution 1080
-```
-
-This will work over the local network, or a private IP space like Tailscale. To serve over the public internet, TLS is required. See [mmserver.default.toml](mmserver.default.toml) for more detail on that and other configuration options.
-
-For instructions on building the server and/or client yourself, see [BUILD.md](BUILD.md).
-
-
-### System Requirements
-
-The following is required to run the server:
-
- - Linux 6.x (for Ubuntu, this means Mantic or Noble)
- - (For AMD/Intel cards) Mesa 24.1.x or later
- - (For NVIDIA cards) [Vulkan drivers](https://developer.nvidia.com/vulkan-driver) version 550 or later
- - XWayland (for X11 apps)
-
-The following is required to run the client:
-
- - Ffmpeg 6.x
-
-### Encoder support
-
-Hardware encoding, based on Vulkan Video, is needed to get the best performance and latency. CPU-based encode is available as a fallback, but it's much slower.
-
-To see if your GPU supports video encoding, see the following matrix for your vendor: [AMD](https://en.wikipedia.org/wiki/Unified_Video_Decoder#Format_support) • [NVIDIA](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new)
-
-Note that with the `ffmpeg` feature, linking against a system-installed `ffmpeg` is supported, which may allow you to use specific CPU-based codecs not considered in this table.
-
-| Codec | CPU | AMD | NVIDIA | Intel[^1] |
-| ----- | :-: | :-: | :----: | :---: |
-| H.264 |  ❌ |  ✔️  |   ✔️    |   ❔  |
-| H.265 |  ✔️  |  ✔️  |   ✔️    |   ❔  |
-|  AV1  |  ✔️  |  ❌ |   ❌   |   ❌  |
-
-[^1]: I don't have an Intel GPU available to test, and it's difficult to find information online about driver/card support for hardware encode. Please let me know how it goes!

docs/.gitignore

@@ -0,0 +1,3 @@
+# autogenerated
+content/reference
+build/

docs/config.toml

@@ -0,0 +1,15 @@
+base_url = "https://colinmarc.github.io/magic-mirror"
+theme = "anemone"
+compile_sass = false
+build_search_index = false
+
+[markdown]
+highlight_code = true
+
+[extra]
+twitter_card = false
+header_nav = [
+  { url = "/", name_en = "/home/"},
+  { url = "https://github.com/colinmarc/magic-mirror", name_en = "/github/"},
+  { url = "", name_en = "/discord/"},
+]

docs/content/_index.md

@@ -0,0 +1,40 @@
++++
++++
+
+# Magic Mirror 🪞✨
+
+This page contains documentation for [Magic Mirror](github.com/colinmarc/magic-mirror),
+an open-source game streaming and remote desktop tool for linux hosts.
+
+### Download
+
+These links always point to the latest release.
+
+ - 💾 [Server [mmserver-0.5.6]](https://github.com/colinmarc/magic-mirror/releases/tag/mmserver-v0.5.6)
+ - 💾 [Command-Line Client [mmclient-0.4.1]](https://github.com/colinmarc/magic-mirror/releases/tag/mmclient-v0.4.1)
+ - 💾 [macOS GUI Client](https://github.com/colinmarc/magic-mirror-swiftui/releases/latest)
+
+### Setup Guides
+
+Start here to get things up and running.
+
+ - ⚙️  [Server Setup](@/setup/server.md)
+ - ⚙️  [Client Setup](@/setup/client.md)
+<!-- - ⚙️  [Running on a Cloud VPS](./setup/vps.md) -->
+<!-- - ⚙️  [Troubleshooting and Known Issues](@/setup/troubleshooting.md) -->
+
+### Reference
+
+Autogenerated from the code.
+
+ - 📖 [Configuration Reference](@/reference/config.md)
+ - 📖 [Protocol Reference](@/reference/protocol.md)
+ - 📖 [Rustdoc for `mm-protocol`](./doc/mm_protocol)
+ - 📖 [Rustdoc for `mm-client-common`](./doc/mm_client_common)
+
+### Resources
+
+Get help, report issues, make friends.
+
+ - ⁉️  [Issue Tracker](https://github.com/colinmarc/magic-mirror/issues)
+ - 💬 [Discord Chat](https://discord.gg/v22G644DzS)

docs/content/setup/client.md

@@ -0,0 +1,50 @@
++++
+title = "Client Setup"
+
+[extra]
+toc = true
++++
+
+## macOS GUI Client
+
+The native macOS client can be downloaded from [the releases page](https://github.com/colinmarc/magic-mirror-swiftui/releases/latest).
+
+It should work out of the box on ARM and Intel Macs running macOS 10.14 or
+later.
+
+## Installing the commandline client
+
+There is also a cross-platform commandline client, `mmclient`. You can download
+it [here](https://github.com/colinmarc/magic-mirror/releases/tag/mmclient-v0.4.1).
+
+The commandline client requires `ffmpeg` 6.0 or later to be installed on the
+system. It also requires up-to-date Vulkan drivers.
+
+## Building mmclient
+
+The following are required to build the client and its dependencies:
+
+```
+rust (MSRV 1.77.2)
+nasm
+cmake
+protoc
+libxkbcommon (linux only)
+libwayland-client (linux only)
+alsa (linux only)
+ffmpeg 6.x
+```
+
+Besides Rust itself, the following command will install everything on ubuntu:
+
+```
+apt install \
+    nasm cmake protobuf-compiler libxkbcommon-dev libwayland-dev libasound2-dev \
+    ffmpeg libavutil-dev libavformat-dev libavdevice-dev libavfilter-dev
+```
+
+Or using homebrew on macOS:
+
+```
+brew install nasm cmake ffmpeg@6 protobuf
+```

docs/content/setup/server.md

@@ -0,0 +1,143 @@
++++
+title = "Server Setup"
+
+[extra]
+toc = true
++++
+
+## Quickstart
+
+First, grab [the latest server release](https://github.com/colinmarc/magic-mirror/releases/tag/mmserver-v0.5.6) and untar it somewhere:
+
+```sh
+curl -fsSL "https://github.com/colinmarc/magic-mirror/releases/download/mmserver-v0.5.6/mmserver-v0.5.6-linux-amd64.tar.gz" \
+    | tar zxv
+cd mmserver-0.5.6
+```
+
+Then, create a [configuration file](@/reference/config.md) with at least one application definition:
+
+```toml
+# mmserver.toml
+[apps.steam-gamepadui]
+command = ["steam", "-gamepadui"]
+xwayland = true
+```
+
+Then you can start the server like so:
+
+```
+$ ./mmserver -C config.toml
+2024-12-09T16:57:30.989261Z  INFO mmserver: listening on [::1]:9599
+```
+
+You can also create a configuration directory, and add a file (json or toml) for each application:
+
+```sh
+mkdir apps.d
+echo 'command = ["steam", "-gamepadui"]' > apps.d/steam.toml
+./mmserver -i apps.d
+```
+
+## Connectivity
+
+By default, mmserver only listens on `localhost`, which is not terribly
+useful. There are a few different options to configure which socket address the
+server listens for connections on.
+
+The easiest is to bind to a local IP, or use a VPN like wireguard or tailscale:
+
+```toml
+# config.toml
+[server]
+bind = "192.168.1.37"
+```
+
+Or from the command line:
+
+```sh
+mmserver --bind $(tailscale ip -4):9599
+```
+
+If you'd like to stream on a public IP, or on all interfaces (with `0.0.0.0`),
+mmserver requires that you set up a TLS certificate and key:
+
+```toml
+# config.toml
+[server]
+tls_cert = "/path/to/tls.key"
+tls_key = "/path/to/tls.cert"
+```
+
+Generating such certificates and adding them to the client is out of scope for
+this guide. Note that while all Magic Mirror traffic is encrypted with TLS
+(whether you supply certificates or not), no _authentication_ is performed on
+incoming connections.
+
+Finally, you can also use `--bind-systemd` or `bind_systemd = true` to bind to a
+[systemd socket](https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html).
+
+## System Requirements
+
+The following is required to run the server:
+
+ - Linux 6.x (for Ubuntu, this means Mantic or Noble)
+ - (For AMD/Intel cards) Mesa 24.3.x or later
+ - (For NVIDIA cards) [Vulkan drivers](https://developer.nvidia.com/vulkan-driver) version 550 or later
+ - XWayland (for X11 apps)
+
+## Hardware/software encoding
+
+Magic Mirror uses video compression codecs to stream the game over the wire.
+Hardware encoding using the GPU is needed to get the best performance and latency.
+CPU-based encode is available as a fallback, but it's slower, albeit slightly
+higher quality.
+
+To see if your GPU supports video encoding, see the following matrix for your vendor:
+ - [AMD](https://en.wikipedia.org/wiki/Unified_Video_Decoder#Format_support)
+ - [NVIDIA](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new)
+
+Note that with the `ffmpeg_encode` feature, linking against a system-installed `ffmpeg`
+is supported, which may allow you to use specific CPU-based codecs not considered
+in this table.
+
+| Codec | CPU | AMD | NVIDIA | Intel |
+| ----- | :-: | :-: | :----: | :---: |
+| H.264 |  ❌ |  ✅ |   ✅   |   ❔  |
+| H.265 |  ✅ |  ✅ |   ✅   |   ❔  |
+|  AV1  |  ✅ |  ❌ |   ❌   |   ❌  |
+
+## Building `mmserver` from source
+
+The following are required to build the server and its dependencies:
+
+```
+rust (MSRV 1.77.2)
+nasm
+cmake
+protoc
+libxkbcommon
+```
+
+Besides Rust itself, the following command will install everything on ubuntu:
+
+```
+apt install nasm cmake protobuf-compiler libxkbcommon-dev
+```
+
+Then you should be good to go:
+
+```
+cd mm-server
+cargo build --bin mmserver [--release]
+```
+
+### Feature flags
+
+The following feature flags are available:
+
+ - `vulkan_encode` (on by default) - enables hardware encode
+ - `svt_encode` (on by default) - enables svt-av1 and svt-hevc for CPU encode
+ - `ffmpeg_encode` - allows using system-installed ffmpeg to do CPU encode
+
+Note that `ffmpeg_encode` takes precedence over `svt_encode` if enabled, but the server will always choose hardware encode if available on your platform.