DiamondLightSource / DiamondLightSource/fastcs
EpicsDocsOptions defaults to writing .md files into cwd
- Dominant language
- Python
- Stars
- 6
- Forks
- 8
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 3
Description
## Summary
`EpicsDocsOptions.output_dir` defaults to `Path(".")`, so any IOC that constructs `EpicsDocsOptions()` without arguments will silently drop `{controller_id}.md` (one per top-level controller) plus `index.md` into whatever directory the IOC was launched from.
For us this means launching `fastcs-catio` from a repo root creates an untracked `BL12I-EA-RIO-01.md` in the working tree on every start.
## Where
- `src/fastcs/transports/epics/options.py:13` — `output_dir: Path = Path(".")`
- `src/fastcs/transports/epics/emission.py:116` `emit_docs_files()` — `path = output_dir / f"{name}{DOCS_EXT}"` then `path.write_text(...)`, called from both CA (`ca/transport.py:49`) and PVA (`pva/transport.py:46`) transports whenever `self.docs` is set.
The sibling `EpicsGUIOptions` has the same `Path(".")` default but is almost always overridden by callers (we do, in `fastcs_catio/__main__.py`). The docs option tends to be left at its default because the typical use is just `EpicsDocsOptions()`.
Tested against fastcs 0.14.0.
## Suggested fix
A few options, in rough order of preference:
1. Drop the default entirely and make `output_dir` required, so callers must opt into a location.
2. Default to something less surprising than cwd — e.g. a `docs-gen/` subdir, or `None` meaning "don't emit". Same treatment would make sense for `EpicsGUIOptions.output_dir`.
3. At minimum, document the cwd default prominently on the dataclass so users know to set it.
Happy to send a PR if you have a preference.
Contributor guide
Assessment
This issue has not been assessed yet.