Add documentation site with Zensical (#173)

* Add documentation site with Zensical

- Add docs/ directory with documentation pages (index, getting-started,
  usage, backup-strategy, contributing)
- Add zensical.toml configuration for the docs site
- Add docs.yml workflow for building and deploying to GitHub Pages
- Update update-readme.yml to use uv instead of pip
- Add docs shield badge to README.md
- Add section markers to README.md for markdown-code-runner integration
- Add Plausible analytics integration
- Domain: rsync-time-machine.nijho.lt

* Update README.md

* Fix pre-commit linting issues

* Update Plausible analytics script

* Use README sections for contributing.md content

* chore(docs): update TOC

* Move Questions section to README for consistency

* chore(docs): update TOC

* Fix heading levels in contributing section

Changed headings from ### to ## to maintain proper heading hierarchy
(# Contributing → ## How to Contribute, ## Development Setup, etc.)

* chore(docs): update TOC

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: basnijholt <[email protected]>

Author: basnijholt

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14.2'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: |
+          uv sync --group docs
+          uv pip install -e .
+
+      - name: Generate docs content
+        run: uv run python docs/generate.py
+
+      - name: Build documentation
+        run: uv run zensical build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/update-readme.yml

@@ -18,17 +18,12 @@ jobs:
 
       - name: Set up Python
         uses: actions/setup-python@v6
-        with:
-          python-version: '3.14.2'
 
-      - name: Install Python dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install markdown-code-runner
-          pip install -e .
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
 
       - name: Run markdown-code-runner
-        run: markdown-code-runner README.md
+        run: uvx --with . markdown-code-runner README.md
 
       - name: Commit updated README.md
         id: commit

README.md

@@ -9,13 +9,18 @@
 [![License](https://img.shields.io/github/license/basnijholt/rsync-time-machine.py)](https://github.com/basnijholt/rsync-time-machine.py/blob/main/LICENSE)
 [![Downloads](https://img.shields.io/pypi/dm/rsync-time-machine)](https://pypi.python.org/pypi/rsync-time-machine)
 ![Open Issues](https://img.shields.io/github/issues-raw/basnijholt/rsync-time-machine.py)
+[![Docs](https://img.shields.io/badge/docs-rsync--time--machine.nijho.lt-blue)](https://rsync-time-machine.nijho.lt)
+
+<!-- SECTION:intro:START -->
 
 Introducing `rsync-time-machine.py` - a Python port of the [`rsync-time-backup`](https://github.com/laurent22/rsync-time-backup) script, offering Time Machine-style backups using rsync. It creates incremental backups of files and directories to the destination of your choice. The backups are structured in a way that makes it easy to recover any file at any point in time. 🚀
 
 It works on Linux, macOS, and Windows (via WSL or Cygwin). The main advantage over Time Machine is flexibility, as it can backup from/to any filesystem and works on any platform. You can also backup to a Truecrypt drive without any problem. 😃
 
 `rsync-time-machine.py` is fully tested, has no external dependencies (only Python ≥3.7 🐍), is fully compatible with [`rsync-time-backup`](https://github.com/laurent22/rsync-time-backup), offers pretty terminal output, and is fully typed! 🎉
 
+<!-- SECTION:intro:END -->
+
 <details><summary><b><u>[ToC]</u></b> 📚</summary>
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -33,11 +38,17 @@ It works on Linux, macOS, and Windows (via WSL or Cygwin). The main advantage ov
 - [:arrows_counterclockwise: How to Restore](#arrows_counterclockwise-how-to-restore)
 - [:star: Featured on](#star-featured-on)
 - [:heart: Support and Contributions](#heart-support-and-contributions)
+- [How to Contribute](#how-to-contribute)
+- [Development Setup](#development-setup)
+- [Code Style](#code-style)
+- [Questions?](#questions)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 </details>
 
+<!-- SECTION:features:START -->
+
 ## :star2: Features
 
 * 📁 Each backup is in its own folder named after the current timestamp.
@@ -49,6 +60,8 @@ It works on Linux, macOS, and Windows (via WSL or Cygwin). The main advantage ov
 * 🧹 Automatically purge old backups based on a configurable expiration strategy.
 * 🔗 "latest" symlink that points to the latest successful backup.
 
+<!-- SECTION:features:END -->
+
 ## :books: Usage
 
 To use `rsync-time-machine.py`, you'll need to provide source and destination paths, along with any desired options:
@@ -130,6 +143,8 @@ options:
 
 Please refer to the original [`rsync-time-backup`](https://github.com/laurent22/rsync-time-backup) README for a list of options, as they have been preserved in the Python port.
 
+<!-- SECTION:installation:START -->
+
 ## :hammer_and_wrench: Installation
 
 To install `rsync-time-machine.py`, simply clone the repository:
@@ -147,6 +162,10 @@ wget https://raw.githubusercontent.com/basnijholt/rsync-time-machine.py/main/rsy
 ```
 and use it like `./rsync_time_machine.py --help`
 
+<!-- SECTION:installation:END -->
+
+<!-- SECTION:examples:START -->
+
 ## :bulb: Examples
 
 * Backup the home folder to backup_drive:
@@ -163,10 +182,18 @@ and use it like `./rsync_time_machine.py --help`
 
 For more examples and detailed usage instructions, please refer to the original [`rsync-time-backup`](https://github.com/laurent22/rsync-time-backup) README.
 
+<!-- SECTION:examples:END -->
+
+<!-- SECTION:expiration:START -->
+
 ## :calendar: Backup Expiration Logic
 
 Backup sets are automatically deleted following a simple expiration strategy defined with the `--strategy` flag. The default strategy is `1:1 30:7 365:30`. Please see the original README for a detailed explanation.
 
+<!-- SECTION:expiration:END -->
+
+<!-- SECTION:exclusion:START -->
+
 ## :page_facing_up: Exclusion File
 
 An optional exclude file can be provided as a third parameter, compatible with the `--exclude-from` parameter of rsync.
@@ -210,18 +237,34 @@ See [this tutorial](https://web.archive.org/web/20230126121643/https://sites.goo
 
 </details>
 
+<!-- SECTION:exclusion:END -->
+
+<!-- SECTION:lock:START -->
+
 ## :lock: Built-in Lock
 
 The script is designed so that only one backup operation can be active for a given directory, avoiding conflicts.
 
+<!-- SECTION:lock:END -->
+
+<!-- SECTION:rsync-options:START -->
+
 ## :gear: Rsync Options
 
 To display, add, or remove rsync options, use the `--rsync-get-flags`, `--rsync-append-flags`, or `--rsync-set-flags` options.
 
+<!-- SECTION:rsync-options:END -->
+
+<!-- SECTION:no-auto-expire:START -->
+
 ## :no_entry_sign: No Automatic Backup Expiration
 
 Use the `--no-auto-expire` flag to disable the default behavior of purging old backups when out of space.
 
+<!-- SECTION:no-auto-expire:END -->
+
+<!-- SECTION:restore:START -->
+
 ## :arrows_counterclockwise: How to Restore
 
 Restoring files from the backup is simple, as the script creates a backup in a regular directory. You can easily copy the files back to the original directory using a command like:
@@ -234,14 +277,63 @@ Consider using the `--dry-run` option to check what exactly is going to be copie
 
 You can also restore files using any file explorer, including Finder on macOS or the command line.
 
+<!-- SECTION:restore:END -->
+
+<!-- SECTION:featured:START -->
+
 ## :star: Featured on
 
 - the Real Python podcast: [Episode 158: Building Python CI With Docker & Applying for a Hacker Initiative Grant @ 00:26:28](https://realpython.com/podcasts/rpp/158/#t=1588)
 - Y Combinator Hacker News: [Python Port of 600 Line Bash Script: rsync-time-machine.py for Rsync Backups](https://news.ycombinator.com/item?id=35933238) (self-posted)
 - Reddit /rpython: [Ported a popular (untested) 600+ Line Bash Script 📜 to Python 🐍: Introducing rsync-time-machine.py for Time Machine-Style Backups Using Rsync 🔄⏰](https://www.reddit.com/r/Python/comments/13gtmz2/ported_a_popular_untested_600_line_bash_script_to/) (self-posted)
 
+<!-- SECTION:featured:END -->
+
+<!-- SECTION:support:START -->
+
 ## :heart: Support and Contributions
 
 We appreciate your feedback and contributions! If you encounter any issues or have suggestions for improvements, please file an issue on the GitHub repository. We also welcome pull requests for bug fixes or new features.
 
+<!-- SECTION:support:END -->
+
+<!-- SECTION:contributing:START -->
+
+## How to Contribute
+
+1. **Report Issues**: Found a bug or have a feature request? [Open an issue](https://github.com/basnijholt/rsync-time-machine.py/issues)
+2. **Submit Pull Requests**: Bug fixes and new features are welcome
+3. **Improve Documentation**: Help us make the docs better
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/basnijholt/rsync-time-machine.py.git
+cd rsync-time-machine.py
+
+# Install development dependencies with uv
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+```
+
+## Code Style
+
+This project uses:
+
+- **Ruff** for linting and formatting
+- **pytest** for testing
+- Type hints throughout the codebase
+
+## Questions?
+
+Join the [GitHub Discussions](https://github.com/basnijholt/rsync-time-machine.py/discussions) for help and community support.
+
+<!-- SECTION:contributing:END -->
+
 Happy backing up! 💾🕰️🎉

docs/CNAME

@@ -0,0 +1 @@
+rsync-time-machine.nijho.lt

docs/backup-strategy.md

@@ -0,0 +1,31 @@
+---
+icon: lucide/calendar
+---
+
+# Backup Strategy
+
+rsync-time-machine uses an intelligent backup expiration strategy to manage disk space while keeping important historical snapshots.
+
+## Backup Expiration Logic
+
+<!-- CODE:START -->
+<!-- from generate import readme_section -->
+<!-- print(readme_section("expiration")) -->
+<!-- CODE:END -->
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+Backup sets are automatically deleted following a simple expiration strategy defined with the `--strategy` flag. The default strategy is `1:1 30:7 365:30`. Please see the original README for a detailed explanation.
+
+<!-- OUTPUT:END -->
+
+## No Automatic Backup Expiration
+
+<!-- CODE:START -->
+<!-- from generate import readme_section -->
+<!-- print(readme_section("no-auto-expire")) -->
+<!-- CODE:END -->
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+Use the `--no-auto-expire` flag to disable the default behavior of purging old backups when out of space.
+
+<!-- OUTPUT:END -->

docs/contributing.md

@@ -0,0 +1,56 @@
+---
+icon: lucide/heart-handshake
+---
+
+# Contributing
+
+<!-- CODE:START -->
+<!-- from generate import readme_section -->
+<!-- print(readme_section("support")) -->
+<!-- CODE:END -->
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+We appreciate your feedback and contributions! If you encounter any issues or have suggestions for improvements, please file an issue on the GitHub repository. We also welcome pull requests for bug fixes or new features.
+
+<!-- OUTPUT:END -->
+
+<!-- CODE:START -->
+<!-- from generate import readme_section -->
+<!-- print(readme_section("contributing")) -->
+<!-- CODE:END -->
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+1. **Report Issues**: Found a bug or have a feature request? [Open an issue](https://github.com/basnijholt/rsync-time-machine.py/issues)
+2. **Submit Pull Requests**: Bug fixes and new features are welcome
+3. **Improve Documentation**: Help us make the docs better
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/basnijholt/rsync-time-machine.py.git
+cd rsync-time-machine.py
+
+# Install development dependencies with uv
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+```
+
+## Code Style
+
+This project uses:
+
+- **Ruff** for linting and formatting
+- **pytest** for testing
+- Type hints throughout the codebase
+
+## Questions?
+
+Join the [GitHub Discussions](https://github.com/basnijholt/rsync-time-machine.py/discussions) for help and community support.
+
+<!-- OUTPUT:END -->