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

[ErikBjare]

Fixes #1171

This PR addresses concerns about potentially confusing example code by significantly improving the documentation structure and safety practices.

Changes

• Removed raw_events.py example that performed destructive operations without clear warnings
• Created comprehensive working-with-data.rst guide with three levels:
  • Canonical Events (recommended for most users)
  • Custom Queries (for specialized analysis)
  • Raw Events (advanced, with proper warnings)
• Added proper page redirects using sphinxext-rediraffe extension
• Restructured examples section with clearer progression from basic to advanced
• Emphasized safety practices: testing modes, dry-run operations, comprehensive examples from aw-client repo

Key Improvements

• Users now start with canonical events (same as web UI) rather than raw bucket access
• All examples point to production-ready code in aw-client repository
• Safety warnings prominently displayed throughout
• Proper redirects maintain existing bookmark/link functionality
• Better organization with clear learning path

The new documentation provides a much better user experience while maintaining all functionality.

---

Important

Improved documentation structure and safety by adding a new guide, restructuring examples, and ensuring proper redirects.

• Documentation Restructure:
  • Removed raw_events.py example due to unsafe operations.
  • Created working-with-data.rst guide with sections on Canonical Events, Custom Queries, and Raw Events.
  • Restructured examples.rst for clearer progression from basic to advanced topics.
• Safety Enhancements:
  • Emphasized safety practices like testing modes and dry-run operations in working-with-data.rst.
  • All examples now point to production-ready code in the aw-client repository.
• Redirects and Configuration:
  • Added sphinxext-rediraffe to pyproject.toml and conf.py for handling redirects.
  • Updated Makefile with redirectcheck target to ensure proper redirects.
  • Added redirects.txt for managing page redirects.

^{This description was created by for df6d178. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 9361d59 in 1 minute and 38 seconds. Click for details.

• Reviewed 605 lines of code in 10 files
• Skipped 1 files when reviewing.
• Skipped posting 9 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. Makefile:247

• Draft comment:
  Added the 'redirectcheck' target using the rediraffecheckdiff builder. The implementation looks solid – ensure that error outputs are clear if redirects fail.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to ensure that error outputs are clear if redirects fail. This falls under the category of asking the author to ensure something, which is against the rules.

2. pyproject.toml:28

• Draft comment:
  Dependency 'sphinxext-rediraffe' has been added to support proper redirects. Verify that the specified version (^0.2.7) remains compatible with your Sphinx build.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is about a dependency change, specifically the addition of 'sphinxext-rediraffe'. It asks the PR author to verify compatibility, which is against the rules. The comment does not provide a specific suggestion or point out a specific issue with the code.

3. src/conf.py:44

• Draft comment:
  The rediraffe extension is now configured with 'rediraffe_redirects' and 'rediraffe_branch'. Confirm that using 'HEAD~1' is appropriate for your redirect mapping strategy.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% This comment violates the rule about not asking for confirmations or verifications. It's asking the author to confirm their intention with the HEAD1 setting. If there was a specific known issue with using HEAD1, that would be different, but this is just asking for confirmation without providing any concrete reason why it might be problematic. Maybe HEAD1 could actually cause serious issues in some redirect scenarios and this is a valid concern? Maybe this is a common source of problems with rediraffe? Even if HEAD1 could potentially cause issues, the comment doesn't explain what those issues would be or suggest a better alternative. It's just asking for confirmation without providing actionable guidance. The comment should be deleted as it violates the rule about not asking authors to confirm their intentions without providing specific actionable feedback.

4. src/examples.rst:1

• Draft comment:
  The examples page now provides a clear roadmap—from canonical events to advanced topics—with a nicely structured toctree. This should improve usability for new users.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative, describing changes made to the examples page and its expected impact on usability. It does not provide any actionable feedback or suggestions for improvement.

5. src/examples/querying-data.rst:1

• Draft comment:
  This page now clearly indicates that it has been moved and uses an automatic redirect. Consider adding fallback content for users with JavaScript disabled.
• Reason this comment was not posted:
  Comment looked like it was already resolved.

6. src/examples/working-with-data.rst:1

• Draft comment:
  The new 'Working with ActivityWatch Data' guide is comprehensive and well-organized, covering canonical events, custom queries, and raw events along with safety best practices.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative, providing feedback on the quality of a guide. It does not offer any actionable suggestions or raise any concerns about the code changes.

7. src/index.rst:39

• Draft comment:
  The table of contents has been updated to remove deprecated pages (querying-data, writing-watchers, extending). Ensure that external links and bookmarks are updated accordingly.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative, as it is asking the author to ensure that external links and bookmarks are updated. It does not provide a specific code suggestion or ask for a specific test to be written. It also does not address any potential issues with the code itself.

8. src/redirects.txt:1

• Draft comment:
  A redirect mapping for 'examples/extending.rst' is provided. Confirm that this redirect aligns with the new documentation structure, or consider redirecting to a more specific page if necessary.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to confirm the alignment of a redirect with the new documentation structure. This falls under asking the author to confirm their intention, which is against the rules. The comment does not provide a specific suggestion or point out a clear issue, so it should be removed.

9. Makefile:249

• Draft comment:
  Typographical issue: The string "rediraffecheckdiff" (and correspondingly the output directory "$(BUILDDIR)/rediraffe") appears to be a misspelling. It likely should be "redirectcheckdiff" (and "$(BUILDDIR)/redirect") or another correct term. Please verify and correct the spelling.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% The term "rediraffe" appears to be an intentional name, likely a Sphinx extension or tool. The consistency between the build target name and directory suggests this is not a typo. Without more context about Sphinx extensions, I should assume the author knows what they're doing. The comment is questioning something that's likely intentional. I could be wrong - maybe it really is a typo and the tool is actually called something else. I don't have complete knowledge of all Sphinx extensions. Even with that uncertainty, the consistency in naming and the fact this is being added as a formal build target strongly suggests this is intentional. We should trust the author's knowledge of their tools. The comment should be deleted as it's questioning something that appears to be intentionally named, and we don't have strong evidence that it's actually incorrect.

Workflow ID: wflow_lPXcpzDTuUMPdTZw

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed b2f2b1d in 58 seconds. Click for details.

• Reviewed 56 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 2 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. src/examples/working-with-data.rst:123

• Draft comment:
  Good addition of the work activities filtering example. Consider adding a brief inline comment explaining what the helper function 'flood' does, as it may not be immediately clear to all users.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

2. src/examples/working-with-data.rst:247

• Draft comment:
  Please ensure the file ends with a newline to comply with style guidelines.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

Workflow ID: wflow_ZzpQE43kOoRJC6uU

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed df6d178 in 28 seconds. Click for details.

• Reviewed 32 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 1 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. src/examples/querying-data.rst:1

• Draft comment:
  Good removal of outdated redirect page. Ensure that the sphinxext-rediraffe configuration fully covers redirection from this file to 'working-with-data', so all old bookmarks are correctly handled.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

Workflow ID: wflow_TO3gbCPXBkkxpSW5

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed db33da4 in 23 seconds. Click for details.

• Reviewed 13 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 1 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. .github/workflows/build.yml:23

• Draft comment:
  Graphviz package added; please confirm it's required for docs generation.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

Workflow ID: wflow_gxOJtH96HbS7F4WF

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}