docs: returners, beacons, reactors, mine, Thorium cleanup

[dwoz]

Summary

Documentation cleanup for the event subsystem — returners, beacons, reactors, mine, Thorium. Ten open issues from the docs backlog, addressed at the source files and pinned by unit tests so future drift is loud.

Issues closed

• [DOCS] Inconsistent and incomplete documentation around returners #62017, [DOCS] Improving returner docs #63367 — returner contexts (--return, master_job_cache, ext_job_cache, event_return) now have a side-by-side table in doc/ref/returners/index.rst covering which side runs the returner, which config file each context reads, and which returner functions are required.
• [DOCS] Beacons and reactors docs (version 3000.3) incorrect for accessing data dict #61616 — doc/topics/reactor/index.rst no longer wrongly mandates data['data'] for beacon-fired events. The master's _minion_event unwraps beacon events before re-firing, so reactors see the beacon payload directly at data['id']. Both shapes (beacons vs event.send) are now distinguished with worked snippets.
• [DOCS] Beacon inotify install instructions do not work #63693, [DOCS] Beacons Inotify Example Wrong for Onedir #65019 — inotify install instructions in doc/topics/beacons/index.rst and salt/beacons/inotify.py no longer recommend the non-existent python-inotify package. Onedir vs system-Python install paths are documented.
• [DOCS] network_settings beacon doesn't list dependency.  #61332 — salt/beacons/network_settings.py now lists pyroute2 as a dependency with install guidance for both onedir and system-Python.
• [DOCS] More Examples of Thorium Complex Reactors Please #61921 — three concrete Thorium SLS examples (load-spike reaction, nginx-flap detection, runner trigger on a tag) added to doc/topics/thorium/index.rst. Each one is parsed by a unit test that also asserts every <module>.<function> reference resolves to a real Thorium function.
• mine.update doesn't update the salt mine when called with module.run #47675 — doc/topics/mine/index.rst now has an "Updating the Mine From a State" section explaining why mine.update inside module.run silently drops the refresh, with three correct alternatives.
• rawfile_json returner doesn't work in any context #39959 — salt/returners/rawfile_json.py docstring now notes that it only implements returner and event_return, so it cannot be used as a master_job_cache or ext_job_cache backend. Code fix is left for the upstream bug.
• hashutil.github_signature does not recognize sha argument #58130 — hashutil.github_signature docstring now explains that challenge_hmac is a single positional <hash>=<hex> string and must be quoted on the CLI. Code fix is left for the upstream bug.

Test plan

• pytest tests/pytests/unit/thorium/test_documented_examples.py tests/pytests/unit/beacons/test_documented_configs.py — 9 passed locally (3 Thorium SLS YAML parses, 3 Thorium module/function existence checks, 1 inotify example validation, 2 beacon-vs-event.send data dict shape pins).
• sphinx -W --keep-going -b html clean on a fresh build (no new warnings).
• sphinx -W --keep-going -b man clean.
• pre-commit clean across every changed file.

Strategy

Branch matrix: oldest-first (3006.x). Merge-forward to 3007.x, 3008.x, master. Event subsystem interface is stable across all four branches; no code logic changes.

Out of scope

• Code fixes for rawfile_json returner doesn't work in any context #39959 (rawfile_json cannot act as a job cache) and hashutil.github_signature does not recognize sha argument #58130 (hashutil.github_signature keyword-arg ambiguity). Documented as known issues with links to the open bugs.