[Cunninger]

Fixes #1095

scripts/sync_env_docs.py inlined each env README into docs/source/environments/<slug>.md but only rewrote HTML src="assets/" image paths. Markdown links such as [example](../../examples/foo.py) stayed relative, so they resolved from the docs stub (wrong depth) on the published site.

This extends stub generation to rewrite markdown links that escape envs/<env>/ into GitHub blob/tree URLs (the convention browsergym / pelican_svg already use by hand). Extra ../ segments that walk out of the repo (e.g. git_env's ../../../examples/...) are stripped so they still map to the intended path.

--check already treats rewritten stubs as the expected content, so leftover relative links fail CI until --fix is run. Regenerated the currently affected stubs (agent_world_model, carla, git, opencode, repl).

Tests:

PYTHONPATH=src:envs uv run pytest tests/scripts/test_sync_env_docs.py -v
uv run python scripts/sync_env_docs.py --check

9 passed; --check is clean.

RFC: not required (docs generator only, no public API / core change).

---

Note

Low Risk
Docs sync tooling and generated markdown only; no runtime API or environment behavior changes.

Overview
Fixes broken example and RFC links on the published docs site when env READMEs are inlined into docs/source/environments/*.md (issue #1095). Previously only HTML assets/ image paths were absolutized; markdown links like ../../examples/foo.py stayed relative and resolved from the wrong path.

scripts/sync_env_docs.py now rewrites markdown links that point outside envs/<env>/ into GitHub blob/tree URLs (and raw for images), including normalizing over-long ../ chains (e.g. git_env’s ../../../examples/...). Stub generation calls this during generate_stub, so --check in CI expects the rewritten output.

Regenerated affected stubs (agent_world_model, carla, git, opencode, repl) and added tests/scripts/test_sync_env_docs.py for path resolution, link rewriting, and integration via generate_stub.

^{Reviewed by Cursor Bugbot for commit 99e46a9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

The current five generated stubs are corrected, but the new general-purpose link rewriter has three confirmed input-handling defects that should be covered before merge:

1. A whitespace-only href such as [text]( ) reaches url.split()[0] and raises IndexError.
2. Relative Markdown links inside fenced code blocks are rewritten, silently changing code examples.
3. Optional Markdown link titles are discarded ([text](path "title") loses "title").

Please make the rewriter code-span/fence aware, handle empty tokenization safely, preserve title suffixes, and add focused regressions. The pre-existing OpenCode README link that resolves to missing DOCS/HF/hf_inference_providers_logprobs.md should also be corrected or explicitly tracked, but it is separate from the parser blockers.

The branch is behind but merge-tree clean. Standard CI never ran (action_required), so after the fixes it also needs a current-main refresh and exact-head Tests/Package CI/docs checks.

View PR

  

_{Sent by Cursor Automation: Release}

[burtenshaw]

The link-rewriting work is now superseded by #1219 (66eb946), which is already on main. Its implementation preserves whitespace-only destinations, optional titles, code spans/fences, and current generated stubs; it also keeps nonexistent/out-of-repository links unchanged. I verified the current script with all six regression tests and sync_env_docs.py --check. Resolving this old branch against main leaves no code delta, and the removed OpenCode page should stay removed. Leaving this open for final disposition rather than reintroducing the older parser.

[burtenshaw]

Closing as superseded by merged #1219. The replacement on main handles relative-link rewriting, including whitespace, titles, code fences and missing targets; its six focused tests pass. This older patch has parser issues and restores a removed OpenCode documentation stub.

[burtenshaw]

Superseded by merged #1219. Resolving against current main preserves its newer parser and leaves no code delta. Six parser regressions and docs synchronization pass; whitespace-only destinations, titles, and code examples are preserved. The obsolete OpenCode page stays removed. No merge needed.