docs: improve examples, add new & updated working-with-data doc, reference aw-client examples better (#152)

* docs: improve examples safety and structure

- Remove potentially confusing raw_events.py example that performed destructive operations
- Create comprehensive working-with-data.rst guide with safety best practices
- Add proper redirects for moved pages using sphinxext-rediraffe
- Restructure examples section with clearer progression from basic to advanced
- Point users to production-ready examples in aw-client repository
- Emphasize testing modes and dry-run practices throughout

Addresses #1171

* fix: add missing redirect for querying-data page

* docs: enhance query language examples and reference existing query_client.py

- Add detailed magic variables example with __CATEGORIES__ usage
- Include minimal and hierarchy query examples from original docs
- Reference the existing query_client.py practical example
- Improve query language documentation while maintaining safety focus

* docs: remove manual redirect page in favor of proper redirect extension

The querying-data.rst page contained a manual JavaScript redirect, but now
that we have sphinxext-rediraffe properly configured in redirects.txt,
the extension handles the redirect automatically. This is cleaner and more
consistent with standard Sphinx practices.

* ci: added graphviz to deps

Author: ErikBjare

.github/workflows/build.yml

@@ -20,7 +20,7 @@ jobs:
         python-version: 3.12
     - name: Install APT dependencies
       run: |
-        sudo apt-get install -y git build-essential apt-utils wget libfreetype6 libpng-dev libopenblas-dev gcc gfortran libsnappy-dev
+        sudo apt-get install -y git build-essential apt-utils wget libfreetype6 libpng-dev libopenblas-dev gcc gfortran libsnappy-dev graphviz
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip poetry

Makefile

@@ -56,6 +56,7 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  redirectcheck to check that deleted files have proper redirects"
 	@echo "  dummy      to check syntax errors of document sources"
 
 .PHONY: clean
@@ -243,8 +244,14 @@ pseudoxml:
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 
+.PHONY: redirectcheck
+redirectcheck:
+	$(SPHINXBUILD) -b rediraffecheckdiff $(ALLSPHINXOPTS) $(BUILDDIR)/rediraffe
+	@echo
+	@echo "Redirect check complete."
+
 .PHONY: dummy
 dummy:
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
-	@echo "Build finished. Dummy builder generates no files."
+	@echo "Build finished. Dummy builder generates no files."

poetry.lock

@@ -25,6 +25,7 @@ m2r2 = "*"
 myst-parser = "*"
 recommonmark = "^0.7.0"
 setuptools = "*"  # needed in Python 3.12+: https://github.com/CrossNox/m2r2/issues/72
+sphinxext-rediraffe = "^0.2.7"
 
 [build-system]
 requires = ["poetry-core"]

pyproject.toml

@@ -41,6 +41,7 @@
     "sphinx.ext.extlinks",
     "sphinx_tabs.tabs",
     "sphinx_click",
+    "sphinxext.rediraffe",
 ]
 
 extlinks = {
@@ -50,6 +51,10 @@
     "gh-aw": ("https://github.com/ActivityWatch/%s", ""),
 }
 
+# Redirects for moved pages
+rediraffe_redirects = "redirects.txt"
+rediraffe_branch = "HEAD~1"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -391,4 +396,4 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
-# texinfo_no_detailmenu = False
+# texinfo_no_detailmenu = False

src/conf.py

@@ -1,9 +1,54 @@
 Examples
 ========
 
-For more examples, see the examples in the aw-client repo: https://github.com/ActivityWatch/aw-client
+This section provides practical examples for working with ActivityWatch, from retrieving your data to extending functionality with custom watchers.
+
+Getting Your Data Out
+----------------------
+
+**Most users should start here:**
+
+.. toctree::
+    :maxdepth: 1
+
+    examples/working-with-data
+
+This comprehensive guide covers:
+
+* **Canonical Events** - Get processed activity data (what the web UI uses)
+* **Custom Queries** - Write your own analysis using the query language
+* **Raw Events** - Advanced direct access to bucket data
+* **Safety Best Practices** - Avoiding data corruption with proper testing and dry-run modes
+
+The guide includes links to production-ready examples from the `aw-client repository <https://github.com/ActivityWatch/aw-client/tree/master/examples>`_.
+
+Writing Your Own Watchers
+-------------------------
+
+Want to collect custom data? **See:**
 
 .. toctree::
-    examples/querying-data
+    :maxdepth: 1
+
     examples/writing-watchers
-    examples/extending
+
+These guides cover:
+
+* **Minimal watcher example** - Get started with a simple template
+* **Full-featured watcher** - Complete example with heartbeats and proper structure
+* **Best practices** - Error handling, bucket management, and testing modes
+* **Rust examples** - Alternative implementation for performance-critical watchers
+
+Watchers are small programs that collect data and send it to ActivityWatch. You can track anything with a timestamp!
+
+Example Code Repository
+-----------------------
+
+The `aw-client examples <https://github.com/ActivityWatch/aw-client/tree/master/examples>`_ contain comprehensive, well-documented examples including:
+
+* **Time analysis** - ``time_spent_today.py``, ``working_hours.py``
+* **Data export** - ``load_dataframe.py`` for pandas integration
+* **Data management** - ``redact_sensitive.py`` with safe dry-run mode
+* **Advanced analysis** - ``suggest_categories.py`` with AI categorization
+
+All examples follow safety best practices with testing modes and error handling.