Skip to content

Commit f011d57

Browse files
authored
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
1 parent b3210e5 commit f011d57

File tree

12 files changed

+432
-217
lines changed

12 files changed

+432
-217
lines changed

.github/workflows/build.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ jobs:
2020
python-version: 3.12
2121
- name: Install APT dependencies
2222
run: |
23-
sudo apt-get install -y git build-essential apt-utils wget libfreetype6 libpng-dev libopenblas-dev gcc gfortran libsnappy-dev
23+
sudo apt-get install -y git build-essential apt-utils wget libfreetype6 libpng-dev libopenblas-dev gcc gfortran libsnappy-dev graphviz
2424
- name: Install dependencies
2525
run: |
2626
python -m pip install --upgrade pip poetry

Makefile

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ help:
5656
@echo " linkcheck to check all external links for integrity"
5757
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
5858
@echo " coverage to run coverage check of the documentation (if enabled)"
59+
@echo " redirectcheck to check that deleted files have proper redirects"
5960
@echo " dummy to check syntax errors of document sources"
6061

6162
.PHONY: clean
@@ -243,8 +244,14 @@ pseudoxml:
243244
@echo
244245
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
245246

247+
.PHONY: redirectcheck
248+
redirectcheck:
249+
$(SPHINXBUILD) -b rediraffecheckdiff $(ALLSPHINXOPTS) $(BUILDDIR)/rediraffe
250+
@echo
251+
@echo "Redirect check complete."
252+
246253
.PHONY: dummy
247254
dummy:
248255
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
249256
@echo
250-
@echo "Build finished. Dummy builder generates no files."
257+
@echo "Build finished. Dummy builder generates no files."

poetry.lock

Lines changed: 114 additions & 19 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

pyproject.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ m2r2 = "*"
2525
myst-parser = "*"
2626
recommonmark = "^0.7.0"
2727
setuptools = "*" # needed in Python 3.12+: https://github.com/CrossNox/m2r2/issues/72
28+
sphinxext-rediraffe = "^0.2.7"
2829

2930
[build-system]
3031
requires = ["poetry-core"]

src/conf.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
"sphinx.ext.extlinks",
4242
"sphinx_tabs.tabs",
4343
"sphinx_click",
44+
"sphinxext.rediraffe",
4445
]
4546

4647
extlinks = {
@@ -50,6 +51,10 @@
5051
"gh-aw": ("https://github.com/ActivityWatch/%s", ""),
5152
}
5253

54+
# Redirects for moved pages
55+
rediraffe_redirects = "redirects.txt"
56+
rediraffe_branch = "HEAD~1"
57+
5358
# Add any paths that contain templates here, relative to this directory.
5459
templates_path = ["_templates"]
5560

@@ -391,4 +396,4 @@
391396

392397
# If true, do not generate a @detailmenu in the "Top" node's menu.
393398
#
394-
# texinfo_no_detailmenu = False
399+
# texinfo_no_detailmenu = False

src/examples.rst

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,54 @@
11
Examples
22
========
33

4-
For more examples, see the examples in the aw-client repo: https://github.com/ActivityWatch/aw-client
4+
This section provides practical examples for working with ActivityWatch, from retrieving your data to extending functionality with custom watchers.
5+
6+
Getting Your Data Out
7+
----------------------
8+
9+
**Most users should start here:**
10+
11+
.. toctree::
12+
:maxdepth: 1
13+
14+
examples/working-with-data
15+
16+
This comprehensive guide covers:
17+
18+
* **Canonical Events** - Get processed activity data (what the web UI uses)
19+
* **Custom Queries** - Write your own analysis using the query language
20+
* **Raw Events** - Advanced direct access to bucket data
21+
* **Safety Best Practices** - Avoiding data corruption with proper testing and dry-run modes
22+
23+
The guide includes links to production-ready examples from the `aw-client repository <https://github.com/ActivityWatch/aw-client/tree/master/examples>`_.
24+
25+
Writing Your Own Watchers
26+
-------------------------
27+
28+
Want to collect custom data? **See:**
529

630
.. toctree::
7-
examples/querying-data
31+
:maxdepth: 1
32+
833
examples/writing-watchers
9-
examples/extending
34+
35+
These guides cover:
36+
37+
* **Minimal watcher example** - Get started with a simple template
38+
* **Full-featured watcher** - Complete example with heartbeats and proper structure
39+
* **Best practices** - Error handling, bucket management, and testing modes
40+
* **Rust examples** - Alternative implementation for performance-critical watchers
41+
42+
Watchers are small programs that collect data and send it to ActivityWatch. You can track anything with a timestamp!
43+
44+
Example Code Repository
45+
-----------------------
46+
47+
The `aw-client examples <https://github.com/ActivityWatch/aw-client/tree/master/examples>`_ contain comprehensive, well-documented examples including:
48+
49+
* **Time analysis** - ``time_spent_today.py``, ``working_hours.py``
50+
* **Data export** - ``load_dataframe.py`` for pandas integration
51+
* **Data management** - ``redact_sensitive.py`` with safe dry-run mode
52+
* **Advanced analysis** - ``suggest_categories.py`` with AI categorization
53+
54+
All examples follow safety best practices with testing modes and error handling.

src/examples/extending.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

src/examples/querying-data.rst

Lines changed: 0 additions & 92 deletions
This file was deleted.

src/examples/raw_events.py

Lines changed: 0 additions & 68 deletions
This file was deleted.

0 commit comments

Comments
 (0)