Documentation review: fix outdated references, remove redundancy

[Copilot]

Documentation had drifted from the codebase: referenced modules that no longer exist, described GUI elements that don't exist, and contained redundant/completed content.

Changes

Removed redundant docs

• terminal-definitions.md (duplicated by terminal-yaml-definitions.md)
• simulator-symbol-alignment.md (completed)
• Moved api-decoupling.md → decisions/0003-api-decoupling-analysis.md

Fixed outdated code references

• xml_parser.py, xml_cache.py, app.py → xml/ subpackage, ui_app.py
• catio_hardware.py → catio_dynamic_*.py modules

Updated for dynamic controller generation

• Replaced "Hardware-Specific Controllers" with "Dynamic Terminal Controllers"
• Documented get_terminal_controller_class() and YAML-driven controller creation

Fixed terminal-yaml-definitions.md

• Single terminal_types.yaml (not multiple category files)
• Added composite_types section, selected field, CoE subindices structure

Removed embedded code

• Replaced all literalinclude directives with descriptions and source links per AGENTS.md

Fixed Mermaid diagrams

• Added mermaid-simple CSS class for simple diagrams to prevent oversized fonts

Instructions to reviewer on how to test:

1. Build docs and verify referenced files exist (e.g., src/catio_terminals/xml/parser.py)
2. Compare docs/explanations/terminal-yaml-definitions.md against src/catio_terminals/terminals/terminal_types.yaml
3. Verify Mermaid diagrams render at reasonable font sizes

Checks for reviewer

• Would the PR title make sense to a user on a set of release notes

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[gilesknap]

I don't think a deep review of the code has been applied to the documentation.

For example the page how-to/use-terminal-editor mentions xml_parser.py which no longer exists.

Take a detailed look at the code and update any such references.

[gilesknap]

The Runtime Data Flow mermaid diagram has HUGE fonts, it looks silly and takes up too much space. Make sure you have reviewed how diagrams look as per the original prompt

[Copilot]

I don't think a deep review of the code has been applied to the documentation.

For example the page how-to/use-terminal-editor mentions xml_parser.py which no longer exists.
...

Fixed in commit 1bd3c6a. The Architecture section in use-terminal-editor.md now correctly references xml/ subpackage with parser.py, pdo.py, pdo_groups.py, coe.py, catalog.py, cache.py instead of the old flat module names.

The Runtime Data Flow mermaid diagram has HUGE fonts, it looks silly and takes up too much space. Make sure you have reviewed how diagrams look as per the original prompt

Fixed in 558ee47. Removed the explicit %%{init: ...fontSize: '14px'...}%% directives from all Mermaid diagrams. They now use Mermaid's default font sizing which should render at a reasonable size.

[Copilot]

fascs-epics-ioc contains a reference to Hardware-Specific Controllers, these are no longer used and the equivalents are dynamically created by the modules catio_dynamic_*.py. change the doc to reflect...

Fixed in 5640ede. Replaced "Hardware-Specific Controllers" section with "Dynamic Terminal Controllers":

• Removed references to catio_hardware.py and explicit controller classes (EL10xxController, etc.)
• Documented how get_terminal_controller_class() creates controllers from YAML definitions
• Added table of catio_dynamic_*.py modules and their roles
• Added link to terminal-yaml-definitions.md for YAML format details

[gilesknap]

Runtime Data Flow mermaid diagram still has huge fonts. This is due to the global css you supplied, I believe. Please override that for simple diagrams like this that do not merit fitting to the page width

[gilesknap]

under The Base Controller heading there is embedded code.

obey the agents.md and never embed code. instead use a brief description and refer to the python module.

[Copilot]

Runtime Data Flow mermaid diagram still has huge fonts. This is due to the global css you supplied, I believe. Please override that for simple diagrams like this that do not merit fitting to the page ...

Fixed in 375143f. Added a mermaid-simple CSS class that overrides the full-width behavior for simple diagrams. The Runtime Data Flow diagram is now wrapped in this class so it uses its natural size instead of expanding to 100% width. Complex diagrams (like the High-Level Architecture) still use full width.

[gilesknap]

explanations/ads-client.html also includes lots of embedded code

[Copilot]

under The Base Controller heading there is embedded code.

obey the agents.md and never embed code. instead use a brief description and refer to the python module.

Fixed in 513b3f5. Replaced all literalinclude directives with brief descriptions and links to source files:

• fastcs-epics-ioc.md: CATioController, CATioControllerAttributeIO, MockADSServer
• ads-client.md: RemoteRoute, AsyncioADSClient, AdsSymbol, MockADSServer

[Copilot]

explanations/ads-client.html also includes lots of embedded code

Already fixed in 513b3f5. The ads-client.md file no longer contains any literalinclude directives or embedded code. All code references have been replaced with brief descriptions and links to the source files. You may need to rebuild the docs to see the updated HTML.

[gilesknap]

closed in favor of #40