Skip to content

Commit ab9cabf

Browse files
johnsideserfjohnsideserf
authored
Merge pull request #35 from johnsideserf/docs/mdbook-site
Add mdBook documentation site with IRC theme
2 parents 8deb9e6 + dcff075 commit ab9cabf

24 files changed

+1794
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [master]
6+
paths: ["docs/**"]
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- uses: peaceiris/actions-mdbook@v2
25+
with:
26+
mdbook-version: latest
27+
28+
- name: Build
29+
run: mdbook build docs
30+
31+
- uses: actions/configure-pages@v5
32+
33+
- uses: actions/upload-pages-artifact@v3
34+
with:
35+
path: docs/book
36+
37+
deploy:
38+
needs: build
39+
runs-on: ubuntu-latest
40+
environment:
41+
name: github-pages
42+
url: ${{ steps.deployment.outputs.page_url }}
43+
steps:
44+
- name: Deploy to GitHub Pages
45+
id: deployment
46+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ Cargo.lock
44
*.swo
55
*~
66
.DS_Store
7+
docs/book/

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
[![CI](https://github.com/johnsideserf/signal-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/johnsideserf/signal-tui/actions/workflows/ci.yml)
44
[![Release](https://img.shields.io/github/v/release/johnsideserf/signal-tui)](https://github.com/johnsideserf/signal-tui/releases/latest)
55
[![License: GPL-3.0](https://img.shields.io/github/license/johnsideserf/signal-tui)](LICENSE)
6+
[![Docs](https://img.shields.io/badge/docs-signal--tui-blue)](https://johnsideserf.github.io/signal-tui/)
67

78
A terminal-based Signal messenger client with an IRC aesthetic. Wraps [signal-cli](https://github.com/AsamK/signal-cli) via JSON-RPC for the messaging backend.
89

‎docs/book.toml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[book]
2+
title = "signal-tui"
3+
description = "Terminal-based Signal messenger client"
4+
authors = ["johnsideserf"]
5+
language = "en"
6+
src = "src"
7+
8+
[build]
9+
build-dir = "book"
10+
11+
[output.html]
12+
default-theme = "coal"
13+
preferred-dark-theme = "coal"
14+
additional-css = ["theme/css/irc-theme.css"]
15+
site-url = "/signal-tui/"
16+
git-repository-url = "https://github.com/johnsideserf/signal-tui"
17+
edit-url-template = "https://github.com/johnsideserf/signal-tui/edit/master/docs/{path}"
18+
19+
[output.html.fold]
20+
enable = true
21+
level = 1

‎docs/src/SUMMARY.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Summary
2+
3+
[Introduction](introduction.md)
4+
5+
---
6+
7+
# User Guide
8+
9+
- [Installation](user-guide/installation.md)
10+
- [Getting Started](user-guide/getting-started.md)
11+
- [Configuration](user-guide/configuration.md)
12+
- [Commands](user-guide/commands.md)
13+
- [Keybindings](user-guide/keybindings.md)
14+
- [Features](user-guide/features.md)
15+
- [Troubleshooting](user-guide/troubleshooting.md)
16+
- [FAQ](user-guide/faq.md)
17+
18+
---
19+
20+
# Developer Guide
21+
22+
- [Architecture](dev-guide/architecture.md)
23+
- [Module Reference](dev-guide/modules.md)
24+
- [Data Flow](dev-guide/data-flow.md)
25+
- [Database Schema](dev-guide/database.md)
26+
- [signal-cli Protocol](dev-guide/protocol.md)
27+
- [Testing](dev-guide/testing.md)
28+
- [Contributing](dev-guide/contributing.md)
29+
- [CI & Releases](dev-guide/ci-releases.md)
30+
- [Roadmap](dev-guide/roadmap.md)

‎docs/src/dev-guide/architecture.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
signal-tui is a terminal Signal client that wraps
6+
[signal-cli](https://github.com/AsamK/signal-cli) via JSON-RPC over stdin/stdout.
7+
It is built on a Tokio async runtime with Ratatui for rendering.
8+
9+
```
10+
+------------+ mpsc channels +----------------+
11+
| TUI | <---------------> | Signal |
12+
| (main | SignalEvent | Backend |
13+
| thread) | UserCommand | (tokio task) |
14+
+------------+ +--------+-------+
15+
|
16+
stdin/stdout
17+
|
18+
+--------v-------+
19+
| signal-cli |
20+
| (child proc) |
21+
+----------------+
22+
```
23+
24+
## Async runtime
25+
26+
The application uses a **multi-threaded Tokio runtime** (via `#[tokio::main]`).
27+
The main thread runs the TUI event loop. signal-cli communication happens in
28+
spawned Tokio tasks that communicate back to the main thread via
29+
`tokio::sync::mpsc` channels.
30+
31+
## Event loop
32+
33+
The main loop in `main.rs` runs on a 50ms tick:
34+
35+
1. **Poll keyboard** -- check for key events via Crossterm (non-blocking, 50ms timeout)
36+
2. **Drain signal events** -- process all pending `SignalEvent` messages from the mpsc channel
37+
3. **Render** -- call `ui::draw()` with the current `App` state
38+
39+
This keeps the UI responsive while processing backend events as they arrive.
40+
41+
## Startup sequence
42+
43+
1. Load config from TOML (or defaults)
44+
2. Check if setup is needed (`account` field empty)
45+
3. If needed: run the setup wizard (signal-cli detection, phone input, QR linking)
46+
4. Open SQLite database (or in-memory for `--incognito`)
47+
5. Spawn signal-cli child process
48+
6. Load conversations and contacts from database + signal-cli
49+
7. Enter the main event loop
50+
51+
## Key dependencies
52+
53+
| Crate | Purpose |
54+
|---|---|
55+
| `ratatui` 0.29 | Terminal UI framework |
56+
| `crossterm` 0.28 | Cross-platform terminal I/O |
57+
| `tokio` 1.x | Async runtime |
58+
| `serde` / `serde_json` | JSON serialization for signal-cli RPC |
59+
| `rusqlite` 0.32 | SQLite database (bundled) |
60+
| `chrono` 0.4 | Timestamp handling |
61+
| `qrcode` 0.14 | QR code generation for device linking |
62+
| `image` 0.25 | Image decoding for inline previews |
63+
| `anyhow` 1.x | Error handling |
64+
| `toml` 0.8 | Config file parsing |
65+
| `dirs` 6.x | Platform-specific directory paths |
66+
| `uuid` 1.x | RPC request ID generation |

‎docs/src/dev-guide/ci-releases.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# CI & Releases
2+
3+
## Continuous integration
4+
5+
CI runs automatically on every push and pull request via
6+
`.github/workflows/ci.yml`.
7+
8+
### CI pipeline
9+
10+
| Step | Command |
11+
|---|---|
12+
| Checkout | `actions/checkout@v4` |
13+
| Rust toolchain | `dtolnay/rust-toolchain@stable` |
14+
| Cache | `Swatinem/rust-cache@v2` |
15+
| Lint | `cargo clippy --tests -- -D warnings` |
16+
| Test | `cargo test` |
17+
18+
CI must pass before merging any PR.
19+
20+
## Release pipeline
21+
22+
Releases are triggered by pushing a version tag. The workflow is defined in
23+
`.github/workflows/release.yml`.
24+
25+
### Triggering a release
26+
27+
```sh
28+
# 1. Update version in Cargo.toml
29+
# 2. Commit the version bump
30+
# 3. Tag and push
31+
git tag v0.3.0
32+
git push origin v0.3.0
33+
```
34+
35+
### Release pipeline steps
36+
37+
1. **Lint & Test** -- same as CI (clippy + tests)
38+
2. **Build** -- compiles release binaries for 4 targets:
39+
40+
| Target | Runner | Archive |
41+
|---|---|---|
42+
| `x86_64-unknown-linux-gnu` | `ubuntu-latest` | `.tar.gz` |
43+
| `x86_64-apple-darwin` | `macos-latest` | `.tar.gz` |
44+
| `aarch64-apple-darwin` | `macos-latest` | `.tar.gz` |
45+
| `x86_64-pc-windows-msvc` | `windows-latest` | `.zip` |
46+
47+
3. **Package** -- creates archives (`tar.gz` on Unix, `zip` on Windows)
48+
4. **Release** -- creates a GitHub Release with auto-generated changelog and
49+
attached archives (via `softprops/action-gh-release@v2`)
50+
51+
### Version tags
52+
53+
Use semantic versioning: `v0.1.0`, `v0.2.0`, `v1.0.0`.
54+
55+
Remember to update the `version` field in `Cargo.toml` before creating the tag.
56+
57+
## Install scripts
58+
59+
Two install scripts are provided in the repository root:
60+
61+
### `install.sh` (Linux / macOS)
62+
63+
```sh
64+
curl -fsSL https://raw.githubusercontent.com/johnsideserf/signal-tui/master/install.sh | bash
65+
```
66+
67+
Downloads the latest release binary for the detected platform and checks for
68+
signal-cli.
69+
70+
### `install.ps1` (Windows)
71+
72+
```powershell
73+
irm https://raw.githubusercontent.com/johnsideserf/signal-tui/master/install.ps1 | iex
74+
```
75+
76+
Downloads the latest Windows release binary and checks for signal-cli.
77+
78+
## Documentation deployment
79+
80+
Documentation is built and deployed via `.github/workflows/docs.yml`. See the
81+
docs workflow for details on how changes to the `docs/` directory trigger a
82+
rebuild and deployment to GitHub Pages.

‎docs/src/dev-guide/contributing.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Contributing
2+
3+
## Getting started
4+
5+
1. Fork the repository and clone your fork
6+
2. Install prerequisites: **Rust 1.70+** and
7+
[signal-cli](https://github.com/AsamK/signal-cli)
8+
3. Build and run tests:
9+
10+
```sh
11+
cargo build
12+
cargo test
13+
```
14+
15+
Use `--demo` mode to test the UI without a Signal account:
16+
17+
```sh
18+
cargo run -- --demo
19+
```
20+
21+
## Making changes
22+
23+
1. Create a feature branch from `master`:
24+
25+
```sh
26+
git checkout -b feature/my-change
27+
```
28+
29+
2. Make your changes. Run checks before committing:
30+
31+
```sh
32+
cargo clippy --tests -- -D warnings
33+
cargo test
34+
```
35+
36+
3. Push your branch and open a pull request against `master`.
37+
38+
## Branch naming
39+
40+
Use prefixed names:
41+
42+
| Prefix | Use case |
43+
|---|---|
44+
| `feature/` | New functionality |
45+
| `fix/` | Bug fixes |
46+
| `refactor/` | Code restructuring |
47+
| `docs/` | Documentation changes |
48+
49+
Examples: `feature/dark-mode`, `fix/unread-count`, `docs/update-readme`
50+
51+
## Code style
52+
53+
- Follow existing patterns in the codebase
54+
- Run `cargo clippy` with warnings-as-errors -- CI enforces this
55+
- Keep commits focused: one logical change per commit
56+
- Write descriptive commit messages
57+
- Reference issue numbers in commits and PRs (e.g., `closes #29`)
58+
59+
## Pull requests
60+
61+
- Create a PR targeting `master`
62+
- Include a clear description of what changed and why
63+
- Reference the issue being addressed if applicable
64+
- Make sure CI passes (clippy + tests)
65+
- Trivial docs-only changes may be committed directly to `master`; all code
66+
changes must go through a PR
67+
68+
## Reporting bugs
69+
70+
Use the
71+
[bug report template](https://github.com/johnsideserf/signal-tui/issues/new?template=bug_report.yml).
72+
Include:
73+
74+
- Your OS and terminal emulator
75+
- signal-tui version (`signal-tui --version` or the release tag)
76+
- Steps to reproduce the issue
77+
78+
## Suggesting features
79+
80+
Use the
81+
[feature request template](https://github.com/johnsideserf/signal-tui/issues/new?template=feature_request.yml).
82+
Describe the problem you're trying to solve before proposing a solution.
83+
84+
## License
85+
86+
By contributing, you agree that your contributions will be licensed under
87+
[GPL-3.0](https://github.com/johnsideserf/signal-tui/blob/master/LICENSE).

0 commit comments

Comments
 (0)