gorakhargosh/watchdog

docs: add more real-world example scripts

Open

#1,190 opened on Aug 4, 2026

View on GitHub
 (2 comments) (0 reactions) (0 assignees)Python (772 forks)batch import
Good first issueHelp welcome :)documentation

Repository metrics

Stars
 (7,396 stars)
PR merge metrics
 (Avg merge 25m) (1 merged PR in 30d)

Description

Description

Following our efforts to improve the documentation and the introduction of the new Examples page, we want to expand our gallery of practical, real-world watchdog configurations.

We would like to invite first-time contributors to add clean, executable example Python scripts for common use cases.

How to contribute:

  1. Choose/Propose a Use Case:
  2. Add a Python script: Create a new Python script under docs/source/examples/ (e.g. docs/source/examples/renaming.py). Make sure it is self-contained and clean.
  3. Link to the docs: Open docs/source/examples.rst and include your script using the literalinclude directive: 
    .. literalinclude:: examples/renaming.py
   :language: python
   :linenos:
  4. Register in tests: Open tests/test_examples.py and add your example script name to the list of tested files so that it gets automatically tested in CI/CD.
  5. Open a PR!

Contributor guide

Research direction
Review the existing examples in docs/source/examples/, the literalinclude usage in docs/source/examples.rst, and the test list in tests/test examples.py to understand the contribution pattern.
Tech stack
python
Domain
documentationtesting
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
PythonGit
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85