docs: refresh translation guidance by pesap · Pull Request #325 · NatLabRockies/R2X

pesap · 2026-09-10T21:42:43Z

Summary

Refresh the R2X documentation structure following the documentation enhancement approach used by r2x-cli PR #185.

Add a concise documentation index and getting-started path.
Add architecture and development guidance grounded in the current package layout.
Organize translation workflows and contributor guidance around current public APIs.
Add explicit instructions for adding, reviewing, and maintaining translated documentation.

Testing Strategy

git diff --check
Repository pre-commit hooks passed when the commit was created.

Stacked PR

This is the first PR in a stack. The Astro migration follows in PR #326.

pesap · 2026-09-10T21:47:41Z

+source model
+    │
+    ▼
+parser package  ──>  r2x_core.System  ──>  R2X translation plugin
+                                                    │
+                                                    ▼
+                                            target r2x_core.System
+                                                    │
+                                                    ▼
+                                             exporter package
+```


This should be a mermaid diagram instead.

Addressed in 27f55cd: replaced the text diagram with a Mermaid flowchart.

Copilot

🟡 Changes recommended

Several documentation inaccuracies currently mislead users or provide failing commands and imports.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Refreshes R2X documentation with improved navigation, onboarding, architecture, development, workflow, and translation guidance.

Changes:

Adds getting-started and API guidance.
Documents architecture and contributor workflows.
Updates documentation navigation and maintenance instructions.

File summaries

File	Summary	Review notes
`docs/source/index.md`	Adds documentation index and navigation.	—
`docs/source/getting_started.md`	Adds installation and workflow guidance.	Moderate: fix CLI installation, package README API examples, and docs build setup.
`docs/source/development.md`	Adds contributor, translation, and build guidance.	Moderate: use the current Sphinx workflow; nit: correct package-specific getter utility naming.
`docs/source/dev_workflow.md`	Updates translation workflow documentation.	Nit: distinguish low-level contributor workflows from public API examples.
`docs/source/architecture.md`	Documents package boundaries and structure.	Nit: describe getter utility modules as package-specific.
`docs/README.md`	Adds documentation landing-page navigation.	—

Review details

Suppressed comments (2)

docs/source/getting_started.md:76

This says the documentation build is separate from the Python environment, but the current CI build uses Sphinx from uv's docs dependency group (sync-args: "--group docs"). The new getting-started path therefore points users away from the actual build setup; describe the uv docs group and Sphinx command instead.

The documentation build is maintained separately from the Python environment.
See [development](development.md) for the documentation commands and the
translation-package maintenance workflow.

docs/source/getting_started.md:11

The getting-started path presents r2x install as the first executable command but never tells readers how to install r2x-cli; the root README has a dedicated CLI-install step at README.md:47-50. A user following this page's prerequisites still has no r2x command, so link to the CLI installation instructions before the plugin commands.

Use Python 3.11, 3.12, or 3.13. For a managed environment, install
[uv](https://docs.astral.sh/uv/). The command-line workflow also requires the
[r2x-cli](https://github.com/NatlabRockies/r2x-cli).

Files reviewed: 6/6 changed files
Comments generated: 5
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

pesap · 2026-09-10T21:57:18Z

+The Astro site is in `docs/` and uses npm with the committed lockfile. From
+that directory:
+
+```bash
+npm ci
+npm run build


Addressed in 27f55cd: restored the current Sphinx and uv docs-group commands used by this PR's CI. The Astro/npm instructions remain scoped to the dependent migration PR.

pesap · 2026-09-10T21:56:56Z

+See the package [README files](https://github.com/NatlabRockies/R2X/tree/main/packages)
+for package-specific entry points and examples.


Addressed in 27f55cd: the getting-started page now points readers to the workflow guides rather than the stale package README examples.

pesap · 2026-09-10T21:56:56Z

+- `translation.py` exposes the public translation function.
+- `plugin_config.py` defines the typed configuration accepted by that function.
+- `config/rules.json` contains declarative source-to-target mappings.
+- `getters.py` and `getters_utils.py` contain derived-field and post-processing logic.


Addressed in 27f55cd: the architecture page now describes getter and post-processing modules as package-specific and lists the observed naming variants.

pesap · 2026-09-10T21:56:57Z

+Each workflow below shows how to install the upstream parser and exporter as
+editable packages and provides a complete Python API example. Use the guide
+that matches your source and target formats.


Addressed in 27f55cd: the workflow page now labels these as contributor-oriented integration examples and directs readers seeking the smaller public API surface to Getting started.

pesap · 2026-09-10T21:56:56Z

+4. Update `getters.py` or `getters_utils.py` only when the value needs
+   computation, context, unit conversion, membership resolution, or
+   post-processing.


Addressed in 27f55cd: the contributor guidance now refers to package-specific getter and post-processing modules instead of assuming a shared filename.

pesap · 2026-09-10T21:52:24Z

Addressed the review feedback in commit 27f55cd: replaced the text architecture diagram with Mermaid, clarified that R2X is an interoperability layer rather than an English-translation product, removed the speculative/trashy development content, restored the Sphinx CI documentation build instructions, corrected package-specific getter module naming, labeled workflow pages as contributor-oriented integration examples, and linked users to the workflow pages instead of stale package README examples.

pesap · 2026-09-10T21:47:55Z

+## Package boundaries
+
+| Layer | Responsibility | Examples |
+| --- | --- | --- |
+| CLI | Discovers plugins, manages the Python environment, and runs pipelines. | `r2x-cli` |
+| Parser | Reads a source format into an `r2x_core.System`. | `r2x-reeds`, `r2x-plexos`, `r2x-sienna` |
+| Core | Provides the shared `System`, `PluginContext`, `Rule`, and rule-engine APIs. | `r2x-core` |
+| Translation | Maps source components and fields to target components and attaches derived data. | This repository |
+| Exporter | Writes a target system to its native format. | `r2x-plexos`, `r2x-sienna` |


Add hyperlink to the repos.

Addressed in 2ae8dcf: the package-boundary table now links to the r2x-cli, parser, r2x-core, and exporter repositories.

pesap · 2026-09-10T21:48:13Z

+- `translation.py` exposes the public translation function.
+- `plugin_config.py` defines the typed configuration accepted by that function.
+- `config/rules.json` contains declarative source-to-target mappings.
+- `getters.py` and `getters_utils.py` contain derived-field and post-processing logic.
+- `tests/` exercises translation behavior and important edge cases.


This is missing important artifacts under config. See r2x-core for the latests.

Addressed in 2ae8dcf: the architecture page now documents the package-specific config/ artifacts, including defaults.json, rules.json, and configuration helpers.

pesap · 2026-09-10T21:48:21Z

+## Rules and getters
+
+Rules handle direct field mappings, defaults, source and target component types,
+and filters. Getter functions handle values that require computation or context,
+such as unit conversion, commitment status, outage rates, memberships, and
+name resolution. Keep these responsibilities separate: put a stable mapping in
+`rules.json`, and put computation that needs code or context in a getter.
+
+When a mapping changes, update the rule and the behavior-focused tests together.
+When a getter changes, test both its returned value and the resulting target
+component or time series where feasible.


Hyperlink to r2x-core

Addressed in 2ae8dcf: the page now links to the r2x-core plugin-system and rules-system documentation.

pesap · 2026-09-10T21:48:48Z

+1. Copy the current English page into the language-specific documentation
+   location defined by the site configuration.
+2. Preserve the page's frontmatter, headings, code fences, links, tables, and
+   command or API names. Translate prose, navigation labels, and accessible
+   text, but do not translate package names, Python identifiers, CLI commands,
+   file paths, or configuration keys.
+3. Add the translated page to the same sidebar position as the English page and
+   add the language to the site language selector when the site supports one.
+4. Record the English source page and its source revision in the translated
+   page's frontmatter or maintenance metadata. This makes stale translations
+   discoverable after an English update.
+5. Have a reviewer who understands the target language and the R2X workflow
+   verify technical meaning, commands, links, and terminology.
+6. Build the documentation and inspect the rendered translated page before
+   merging.


Addressed in 2ae8dcf: removed the out-of-scope documentation-localization section and reduced the development page to repository checks and interoperability-package contribution guidance.

pesap · 2026-09-10T21:56:40Z

Addressed the additional review comments in commit 2ae8dcf: added repository hyperlinks, expanded the architecture package layout to include package-specific config artifacts, linked to the r2x-core plugin and rules documentation, clarified interoperability terminology, and removed the out-of-scope localization/development material from the development guide. The existing Sphinx documentation workflow remains documented and unchanged in this PR.

pesap · 2026-09-10T21:58:52Z

Addressed the latest review feedback in commit 4fb5743: added the missing r2x-core configuration/plugin/rules references, clarified the repository and package responsibilities as interoperability rather than translation, and tightened the scope and wording of the development guide.

pesap · 2026-09-10T22:05:51Z

Addressed the translation_rules.json review in commit e1ec194. The docs now cover the shared r2x_core.PluginConfig asset names and paths, including translation_rules.json, parser_rules.json, exporter_rules.json, file_mapping.json, defaults.json, and package-specific rules.json assets. Development guidance now points contributors to the appropriate configuration asset and config.translation_rules_path.

docs: refresh translation guidance

9de0575

Copilot AI lite review requested due to automatic review settings September 10, 2026 21:42

github-actions Bot added the Docs Improvements or additions to documentation label Sep 10, 2026

pesap mentioned this pull request Sep 10, 2026

docs: migrate site to Astro #326

Open

Copilot started reviewing on behalf of pesap September 10, 2026 21:43 View session

pesap added this pull request to stack #327 September 10, 2026 21:46

pesap commented Sep 10, 2026

View reviewed changes

Copilot AI reviewed Sep 10, 2026

View reviewed changes

docs: address documentation review

27f55cd

pesap commented Sep 10, 2026

View reviewed changes

docs: refine interoperability scope

2ae8dcf

docs: clarify interoperability boundaries

4fb5743

docs: document translation rule assets

e1ec194

		See the package [README files](https://github.com/NatlabRockies/R2X/tree/main/packages)
		for package-specific entry points and examples.

Uh oh!

Conversation

pesap commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing Strategy

Stacked PR

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (2)

Uh oh!

pesap Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pesap commented Sep 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pesap commented Sep 10, 2026

Uh oh!

pesap commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pesap commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pesap commented Sep 10, 2026 •

edited

Loading

pesap Sep 10, 2026 •

edited

Loading

pesap commented Sep 10, 2026 •

edited

Loading