feat: add hot-reload watcher to CrocoDocs CLI

[ndonkoHenri]

Summary by Sourcery

Add a CrocoDocs file-watching CLI workflow for hot-reload docs development.

New Features:

• Add a crocodocs watch CLI subcommand and supporting file-watching pipeline to regenerate docs artifacts on source changes and optionally run a child dev server.

Bug Fixes:

• Correct CrocoDocs manifest route generation so docs/index pages map to the base route rather than an /index suffix.

Enhancements:

• Improve CrocoDocs CLI UX with shared arguments, richer help/description text, and clearer watcher configuration flags.
• Refine CrocoDocs README to describe the watch workflow, watched paths, and configuration tables with clearer formatting.

Build:

• Update website and Taskfile docs commands so yarn start runs crocodocs watch alongside the Docusaurus dev server for hot-reload docs development.

Documentation:

• Improve CrocoDocs and website docs tables and copy to better explain keys, components, and generated artifacts.

[ndonkoHenri]

@sourcery-ai review

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[cloudflare-workers-and-pages]

Deploying flet-website-v2 with    Cloudflare Pages

Latest commit:	d767475
Status:	✅  Deploy successful!
Preview URL:	https://148db790.flet-website-v2.pages.dev
Branch Preview URL:	https://crocodocs-hot-reload.flet-website-v2.pages.dev

View logs

[Copilot]

Pull request overview

Adds a crocodocs watch command to support hot-reload workflows by regenerating CrocoDocs artifacts on filesystem changes, and wires this into the website dev-start flow.

Changes:

• Introduces a standard-library polling watcher (crocodocs watch) that reruns generation after a debounce window and can manage a long-running child process (e.g., Docusaurus).
• Refactors the CrocoDocs CLI to share generate-related flags between generate and watch, adding watcher-specific options.
• Updates website/docs developer workflows (website/package.json, Taskfile, and CrocoDocs README) to use the watcher during yarn start.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
website/package.json	Routes yarn start through crocodocs watch so docs artifacts regenerate while the dev server runs.
tools/crocodocs/src/crocodocs/watch.py	New watcher implementation: scans targets, detects changes, debounces, regenerates, and optionally runs/stops a child process.
tools/crocodocs/src/crocodocs/cli.py	Adds watch subcommand and shared flag plumbing for generation-related overrides.
tools/crocodocs/README.md	Documents the new watch workflow and updates local dev instructions.
sdk/python/Taskfile.yml	Updates serve-docs task to use the new hot-reload start path.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cloudflare-workers-and-pages]

Deploying flet-examples with    Cloudflare Pages

Latest commit:	d767475
Status:	✅  Deploy successful!
Preview URL:	https://9ca5134e.flet-examples.pages.dev
Branch Preview URL:	https://crocodocs-hot-reload.flet-examples.pages.dev

View logs

[FeodorFitsner]

Why I'd prefer watchdog over a hand-rolled polling watcher:

• It's the de-facto Python file-watch library — already a transitive dep in much of the Python ecosystem, not an exotic addition.
• Event-based, zero CPU when idle. The current polling re-stats every watched file every 750 ms. With the examples_root / asset_mappings.examples overlap, that's thousands of stat() syscalls per second on a laptop. Fine on SSD, noticeable on battery / HDD / network mounts.
• Lower save→regen latency. Drops from ~0.75–1.25 s (poll interval + debounce) to just the debounce window (~0.5 s). For hot-reload UX that's the difference between "fast" and "feels instant."
• Cross-platform edge cases already handled: case-insensitive filesystems, symlinks, and rename-as-delete+create. The current detect_changes re-derives this correctly, but it's work we don't need to own.
• Much less code to maintain. ~340 lines of custom watcher → ~50 lines using watchdog.observers.Observer + a debounced handler. Smaller surface area for bugs.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.