DiamondLightSource / DiamondLightSource/fastcs

EpicsDocsOptions defaults to writing .md files into cwd

Open
#379 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.