Support usage of environment variables inside robot documentation

[JokeWaumans]

Summary by CodeRabbit

• New Features
  • Added support for runtime environment variable substitution in test documentation. Documentation strings can now reference environment variables using the %{VAR} syntax pattern, which will be replaced with corresponding values at runtime.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

The changes introduce runtime environment variable substitution into test documentation. A test robot file is updated with a runtime variable token, the parser is enhanced to replace such tokens with corresponding environment values via regex pattern matching, and tox test environments are configured with the necessary variables.

Changes

Cohort / File(s)	Summary
Test Documentation doc/source/robot/example.robot	Extended the Documentation line in the First Test test case by appending a runtime variable token %{RUNTIME_VAR}.
Parser Enhancement mlx/robot2rst/robot_parser.py	Added runtime environment variable substitution logic that searches documentation for patterns matching %{VAR} via regex and replaces them with corresponding values from os.environ.
Test Environment Configuration tox.ini	Configured runtime environment variable RUNTIME_VAR with value "Test env variable" in [testenv:sphinx2.4.5] and [testenv:sphinx-latest]. Added setuptools<70 dependency constraint to [testenv:sphinx2.4.5].

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A token appears in docs so bright,
%{RUNTIME_VAR} takes its flight,
The parser springs with regex cheer,
Environment whispers what to wear,
Variables dance in tox's care! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and directly describes the main change: adding support for using environment variables in robot documentation strings.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch support-env

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@mlx/robot2rst/robot2rst.py`:
- Around line 58-68: The current render_template call unpacks all environment
variables into the top-level template namespace (env_vars via **env_vars), which
risks keyword collisions and exposing secrets; change render_template(rst_file,
parser=parser, suite=..., prefix=..., relationship_config=...,
gen_matrix=gen_matrix, **kwargs, env=env_vars) so the template receives a single
namespaced dict (e.g., env) instead of splatting env_vars, and update templates
to read values as env['MY_VAR'] or env.get('MY_VAR') to avoid collisions and
limit exposure.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Namespace collision risk and unnecessary exposure of all environment variables.

Two concerns with unpacking **env_vars directly into the template keyword arguments:

1. TypeError at runtime if any env-var name collides with an existing keyword argument. If an environment variable happens to be named parser, suite, prefix, gen_matrix, test_type, only, coverages, etc., Python will raise TypeError: got multiple values for keyword argument '…'. While most standard env vars are uppercase, this is not guaranteed—CI systems and users can define arbitrary names.

2. All environment variables (including secrets) become available to the Mako template. Env vars frequently carry credentials (AWS_SECRET_ACCESS_KEY, DATABASE_URL, tokens, etc.). Mako templates can execute arbitrary Python, so any template content—including user-supplied .robot documentation—could exfiltrate secrets into the generated .rst output.

Both problems are solved by passing env vars as a single namespaced dict instead of splatting them into the top-level namespace. Templates would then use ${env['MY_VAR']} instead of ${MY_VAR}.

Proposed fix

-    env_vars = dict(os.environ)
     return render_template(
         rst_file,
         parser=parser,
         suite=rst_file.stem,
         prefix=prefix,
         relationship_config=relationship_config,
         gen_matrix=gen_matrix,
-        **env_vars,
+        env=dict(os.environ),
         **kwargs,
     )

Templates would then reference variables as ${env['MY_VAR']} (or ${env.get('MY_VAR', 'default')}).

🤖 Prompt for AI Agents

In `@mlx/robot2rst/robot2rst.py` around lines 58 - 68, The current render_template
call unpacks all environment variables into the top-level template namespace
(env_vars via **env_vars), which risks keyword collisions and exposing secrets;
change render_template(rst_file, parser=parser, suite=..., prefix=...,
relationship_config=..., gen_matrix=gen_matrix, **kwargs, env=env_vars) so the
template receives a single namespaced dict (e.g., env) instead of splatting
env_vars, and update templates to read values as env['MY_VAR'] or
env.get('MY_VAR') to avoid collisions and limit exposure.

[Letme]

This seems valid- but you opted not to take this.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the Mako template to see if it references environment variables
cat mlx/robot2rst/robot2rst.mako

Length of output: 2958

---

@Letme, you're right to push back on this. After examining the template file, the environment variables aren't even used by the template — which makes this change both risky and unnecessary.

Key findings:

1. The template never references environment variables. The robot2rst.mako template only uses suite, test_type, parser, prefix, relationship_config, gen_matrix, and coverage. There's no code path that accesses env vars like ${MY_VAR} or ${env_vars['MY_VAR']}.

2. Environment variable substitution already happens earlier in the pipeline. Looking at the PR changes, robot_parser.py already handles %{VAR} substitution in test documentation strings using os.environ before the template is ever rendered. The template's generate_body() function only processes parser.variables, not environment variables.

3. This means exposing all env vars to the template serves no purpose — except creating the exact security and collision risks CodeRabbit flagged.

Recommendation:

Remove the env_vars code entirely:

-    env_vars = dict(os.environ)
     return render_template(
         rst_file,
         parser=parser,
         suite=rst_file.stem,
         prefix=prefix,
         relationship_config=relationship_config,
         gen_matrix=gen_matrix,
-        **env_vars,
         **kwargs,
     )

The PR's environment variable feature already works correctly via the parser layer. Adding them to the template context is dead code that creates security exposure.

---

🧬 Code Graph Analysis Results

<no_relevant_code_snippets>
</no_relevant_code_snippets>