Skip to content

Document running experiments across rigs - #295

Merged
bruno-f-cruz merged 1 commit into
mainfrom
docs/cross-rig-execution
Oct 31, 2026
Merged

bruno-f-cruz merged 1 commit into
mainfrom
docs/cross-rig-execution

Conversation

@bruno-f-cruz

Copy link
Copy Markdown
Member

Documents what #291, #292 and #293 added. Docs only, plus docstring fixes that feed the API reference.

New: "Running on other rigs" (docs/articles/remote_execution.md)

Written for someone deploying a second rig, in the order they would do it:

  1. The server: settings table, why the token is required (the server runs any command as its user), serve, and register-task / unregister-task (what the scheduled task does and why it runs in the user's session rather than as a service).
  2. Connecting: RemoteRepository arguments, ensure_running(), and exactly what verify() compares.
  3. Running apps: app.run_async(executor=remote), and what the executor does on top of a local run (working directory, path rewriting, copying Command.inputs), with the limitations.
  4. Data saved on the other machine: register_session, session_directory vs session_directory_unc (which path is valid on which machine), data_roots / to_unc.
  5. Watchdog: both machines in one manifest, the reachability check, and that the manifest is always written.
  6. A troubleshooting table.

Also: a "Remote execution" example page (includes examples/client_behavior_launcher.py), nav entries, and a README bullet.

Fixes found while writing it

  • The behavior launcher example page was broken. Its snippet include was mangled (--8 < --"..."), so the published page showed that literal text instead of the code. Fixed.
  • Stale names in docstrings. XmlRpcExecutor and XmlRpcClient examples referred to RpcClient, RpcExecutor and clabe.rpc._client, none of which exist. They render in the API reference, so they're corrected.
  • XmlRpcServer.submit_command got a type annotation so its docstring renders without a griffe warning.

Review notes

  • Verified: mkdocs build --strict shows no warnings from any page or module touched here, and every cross-reference in the new article resolves. I also checked the rendered HTML for the new pages, the example snippets, and the nav links. Docs only build on a release in CI, so nothing in CI covers this PR.
  • Existing warnings, not touched: the strict build still reports old griffe docstring warnings (e.g. modifiers.py, runnable/_core.py) and two unresolved cross-references (clabe.runnable.RunnableSettings, clabe.stores.confierge.DEFAULT_SCOPE_MAPPING), so --strict cannot be turned on in CI yet.
  • Not documented: Open Ephys launch() (Launch Open Ephys GUI and wait for its API, locally or remotely #294), which isn't merged. Its docstrings are the reference for now; the article has a natural place for a short section once it lands.
  • The README link to the article is an absolute GitHub URL, because the docs home page is built from the README and a relative path breaks there.
  • Claims to double check: ensure_running() and register-task describe Windows Task Scheduler behavior that was only tested with schtasks mocked, so the article describes what the code runs, not what was observed on a rig.

- Add the "Running on other rigs" article: the XML-RPC server and its
  settings, registering it as a scheduled task, RemoteRepository
  (ensure_running, verify, running apps, session directories and network
  shares), and transferring both machines' data with the watchdog
- Add a remote execution example page and nav entries, and mention
  multi-rig experiments in the README
- Fix the behavior launcher example page, which showed the literal text
  of a mangled snippet include instead of the code
- Replace stale RpcClient/RpcExecutor/clabe.rpc names in the XML-RPC
  docstrings, which feed the API reference, and annotate the server's
  submit_command so its docstring renders
@bruno-f-cruz
bruno-f-cruz merged commit 7bc88b0 into main Oct 31, 2026
6 checks passed
@bruno-f-cruz
bruno-f-cruz deleted the docs/cross-rig-execution branch October 31, 2026 06:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant