Draft
Conversation
Reorganize OpenEnv docs from reference-first to content-centric structure
following MCP and TRL documentation patterns.
Changes:
- Create new folder structure: guides/, reference/, environments/
- Move auto-discovery.md to guides/
- Move core.md and cli.md to reference/
- Add section index pages for guides, tutorials, environments, reference
- Update mkdocs.yml with new navigation structure
- Add placeholder files for new content:
- Get Started: installation.md, concepts.md
- Guides: connecting.md, async-sync.md, first-environment.md,
environment-anatomy.md, deployment.md, rl-integration.md, rewards.md
- Community: contributing.md
- Categorize environments by type: Games, Code Execution, Web, Simulation, Conversational
- Include docs audit spreadsheet and reorganization proposal
Next steps:
- Write Priority 1 content: introduction.md, concepts.md, installation.md
- Flesh out guide placeholders with full content
- Add more tutorials (blackjack, chess-training, web-agents)
- Add metadata (authors, dates) to all pages
- Fix formatting issues identified in audit
- Update reference/index.md to remove links to non-existent files - Update tutorials/index.md to mark future tutorials as 'Coming soon' - Fix environment-builder.md links in reference/cli.md and reference/core.md to point to guides/first-environment.md - Add site/ to .gitignore
Remove backslash escaping from all 48 backtick instances that were preventing code blocks from rendering properly.
- Convert Parameters sections to tables for proper rendering - Convert Benefits section to table format - Enable pymdownx.emoji extension for Material theme icons
Markdown requires a blank line between paragraph text and list items for proper <ul> rendering. Without the blank line, list items get rendered inline within a <p> tag.
- quickstart.md is now a brief 5-minute getting started guide - installation.md contains the detailed setup and usage walkthrough - Updated internal links to reflect new structure
Remove individual environment listings from sidebar navigation. Users can browse all environments from the categorized index page.
Show category links (Games, Code Execution, etc.) that anchor to sections on the environments index page.
- Add markdown attribute to centered div for proper rendering - Convert HTML tables to Material grid cards format - Badges, links and text now render correctly
Corrected anchor IDs to match actual generated anchors: - #games-puzzles (not #games--puzzles) - #web-browser (not #web--browser)
MkDocs nav only supports file paths, not URL anchors. Categories are still visible on the environments index page.
…ocs-reorganization
…ocs-reorganization
meta-cla
bot
added
the
CLA Signed
Contributor
Greptile SummaryThis PR reorganizes the OpenEnv documentation from a flat reference-first layout into a content-centric structure with distinct Get Started, Guides, Tutorials, Environments, API Reference, and Community sections. It fixes escaped-backtick code blocks in Issues identified:
Confidence Score: 2/5
Last reviewed commit: 0826a53 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
28
to
41
| @@ -33,6 +37,7 @@ Fast-forward to 2025, GRPO is awesome and this time it's not JUST in theory, it | |||
|
|
|||
| The problem still remains, how do you take these RL algorithms and take them beyond Cartpole? | |||
|
|
|||
| A huge part of RL is giving your algorithms environment access to learn. | |||
| A huge part of RL is giving your algorithms environment access to learn. | |||
Contributor
There was a problem hiding this comment.
Duplicate paragraphs introduced by merge. The following sentences each appear twice in the current file:
It's 2016, RL is popular. You read some papers, it looks promising.(lines 28-29)But in real world: Cartpole is the best you can run on a gaming GPU.(lines 31-32)A huge part of RL is giving your algorithms environment access to learn.(lines 40-41)
Additionally, the list item 2. _parse_result() - Parse JSON → typed observation appears twice with the same numbering (lines 658-659).
Each of these should appear only once in the final file.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/tutorials/openenv-tutorial.md
Line: 28-41
Comment:
Duplicate paragraphs introduced by merge. The following sentences each appear twice in the current file:
- `It's 2016, RL is popular. You read some papers, it looks promising.` (lines 28-29)
- `But in real world: Cartpole is the best you can run on a gaming GPU.` (lines 31-32)
- `A huge part of RL is giving your algorithms environment access to learn.` (lines 40-41)
Additionally, the list item `2. _parse_result() - Parse JSON → typed observation` appears twice with the same numbering (lines 658-659).
Each of these should appear only once in the final file.
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
104
to
107
| - Auto-Discovery API: auto-discovery.md | ||
| - Building an Environment: environment-builder.md | ||
| - Contributing Environments: contributing-envs.md | ||
| - Customizing the Web UI: customizing-web-ui.md |
Contributor
There was a problem hiding this comment.
Stale navigation entries remain in the Guides section. These paths no longer exist in the new structure:
- Auto-Discovery API: auto-discovery.md # moved → guides/auto-discovery.md
- Building an Environment: environment-builder.md # does not exist
- Contributing Environments: contributing-envs.md # does not exist
- Customizing the Web UI: customizing-web-ui.md # does not existThe correct entries already exist in the new structure (lines 92-103). These stale entries should be removed to prevent MkDocs build warnings or failures. Note that auto-discovery.md has been moved to guides/auto-discovery.md and is already correctly referenced in the new "Using Environments" section.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/mkdocs.yml
Line: 104-107
Comment:
Stale navigation entries remain in the Guides section. These paths no longer exist in the new structure:
```yaml
- Auto-Discovery API: auto-discovery.md # moved → guides/auto-discovery.md
- Building an Environment: environment-builder.md # does not exist
- Contributing Environments: contributing-envs.md # does not exist
- Customizing the Web UI: customizing-web-ui.md # does not exist
```
The correct entries already exist in the new structure (lines 92-103). These stale entries should be removed to prevent MkDocs build warnings or failures. Note that `auto-discovery.md` has been moved to `guides/auto-discovery.md` and is already correctly referenced in the new "Using Environments" section.
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+4
to
+46
| This page will contain a streamlined guide to building your first OpenEnv environment. For now, see the [full environment builder guide](../environment-builder.md). | ||
|
|
||
| ## Overview | ||
|
|
||
| Building an OpenEnv environment involves: | ||
|
|
||
| 1. **Define your models** - Action, Observation, and State types | ||
| 2. **Implement the environment** - Core logic in a Python class | ||
| 3. **Create the server** - FastAPI wrapper for HTTP access | ||
| 4. **Package for deployment** - Docker container and manifest | ||
|
|
||
| ## Quick Example | ||
|
|
||
| Here's a minimal environment that echoes back messages: | ||
|
|
||
| ```python | ||
| from pydantic import BaseModel | ||
| from openenv.core import Environment | ||
|
|
||
| class EchoAction(BaseModel): | ||
| message: str | ||
|
|
||
| class EchoObservation(BaseModel): | ||
| echo: str | ||
|
|
||
| class EchoState(BaseModel): | ||
| last_message: str = "" | ||
|
|
||
| class EchoEnvironment(Environment[EchoAction, EchoObservation, EchoState]): | ||
| def reset(self) -> EchoObservation: | ||
| self.state = EchoState() | ||
| return EchoObservation(echo="Ready!") | ||
|
|
||
| def step(self, action: EchoAction) -> tuple[EchoObservation, float, bool]: | ||
| self.state.last_message = action.message | ||
| return EchoObservation(echo=action.message), 0.0, False | ||
| ``` | ||
|
|
||
| ## Next Steps | ||
|
|
||
| - [Environment Anatomy](environment-anatomy.md) - Deep dive into structure | ||
| - [Deployment](deployment.md) - Deploy to Docker and HF Spaces | ||
| - [Full Guide](../environment-builder.md) - Complete documentation |
Contributor
There was a problem hiding this comment.
Broken relative links to environment-builder.md. This file appears in two places but the target does not exist:
- Line 4:
[full environment builder guide](../environment-builder.md)in the "Coming Soon" admonition - Line 46:
[Full Guide](../environment-builder.md)in the "Next Steps" section
The file environment-builder.md was not moved or recreated under the new structure. Either restore the file at docs/environment-builder.md or update these links to point to the correct location (likely environment-anatomy.md or another guide in the "Building Environments" section).
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/guides/first-environment.md
Line: 4-46
Comment:
Broken relative links to `environment-builder.md`. This file appears in two places but the target does not exist:
- Line 4: `[full environment builder guide](../environment-builder.md)` in the "Coming Soon" admonition
- Line 46: `[Full Guide](../environment-builder.md)` in the "Next Steps" section
The file `environment-builder.md` was not moved or recreated under the new structure. Either restore the file at `docs/environment-builder.md` or update these links to point to the correct location (likely `environment-anatomy.md` or another guide in the "Building Environments" section).
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+1
to
+100
| # OpenEnv Documentation Reorganization Proposal | ||
|
|
||
| ## Philosophy | ||
|
|
||
| Following the MCP and TRL documentation patterns, this proposal shifts OpenEnv docs from a "reference-first" to a "content-centric" approach. For a young project, users need: | ||
|
|
||
| 1. **Quick wins** - Get something working in 5 minutes | ||
| 2. **Conceptual understanding** - Why does OpenEnv exist? How does it work? | ||
| 3. **Practical guidance** - How do I do X with OpenEnv? | ||
| 4. **Reference** - API details when I need them | ||
|
|
||
| --- | ||
|
|
||
| ## Proposed Navigation Structure | ||
|
|
||
| ```yaml | ||
| nav: | ||
| - Get Started: | ||
| - Introduction: introduction.md # NEW - What is OpenEnv? Why use it? | ||
| - Quick Start: quickstart.md # EXISTING - 5-min hello world | ||
| - Installation: installation.md # NEW - Detailed installation options | ||
| - Core Concepts: concepts.md # NEW - Key abstractions explained | ||
|
|
||
| - Guides: | ||
| - Using Environments: | ||
| - Auto-Discovery (AutoEnv): guides/auto-discovery.md # MOVED from auto-discovery.md | ||
| - Connecting to Servers: guides/connecting.md # NEW - HTTP, Docker, HF Spaces | ||
| - Async vs Sync: guides/async-sync.md # NEW - Extract from quickstart | ||
| - Building Environments: | ||
| - Your First Environment: guides/first-environment.md # REFACTOR from environment-builder.md | ||
| - Environment Anatomy: guides/environment-anatomy.md # NEW - Deep dive into structure | ||
| - Deployment Options: guides/deployment.md # NEW - Docker, HF Spaces, registries | ||
| - Web Interface: guides/web-interface.md # NEW - Extract from README | ||
| - Training Integration: | ||
| - Using with RL Frameworks: guides/rl-integration.md # NEW - Overview of integrations | ||
| - Reward Design: guides/rewards.md # NEW - How to design reward functions | ||
|
|
||
| - Tutorials: | ||
| - Beginner: | ||
| - OpenEnv in 15 Minutes: tutorials/openenv-tutorial.md # EXISTING | ||
| - Playing Blackjack with RL: tutorials/blackjack.md # NEW - from examples/grpo_blackjack | ||
| - Intermediate: | ||
| - Wordle with GRPO & TRL: tutorials/wordle-grpo.md # EXISTING | ||
| - Training a Chess Agent: tutorials/chess-training.md # NEW | ||
| - Advanced: | ||
| - Building a Custom Game Env: tutorials/custom-game.md # NEW | ||
| - Web Agents with BrowserGym: tutorials/web-agents.md # NEW | ||
|
|
||
| - Environments: | ||
| - Overview: environments/index.md # REFACTOR from environments.md | ||
| - By Category: | ||
| - Games & Puzzles: | ||
| - Echo (Testing): environments/echo.md | ||
| - Snake: environments/snake.md | ||
| - Chess: environments/chess.md | ||
| - Atari: environments/atari.md | ||
| - OpenSpiel: environments/openspiel.md | ||
| - TextArena: environments/textarena.md | ||
| - Code Execution: | ||
| - Coding: environments/coding.md | ||
| - REPL: environments/repl.md | ||
| - Git: environments/git.md | ||
| - Terminal-Bench 2: environments/tbench2.md | ||
| - Web & Browser: | ||
| - BrowserGym: environments/browsergym.md | ||
| - OpenApp: environments/openapp.md | ||
| - Web Search: environments/websearch.md | ||
| - Simulation: | ||
| - Unity ML-Agents: environments/unity.md | ||
| - SUMO Traffic: environments/sumo.md | ||
| - FinRL Trading: environments/finrl.md | ||
| - Conversational: | ||
| - Chat: environments/chat.md | ||
| - DIPG Safety: environments/dipg.md | ||
|
|
||
| - API Reference: | ||
| - Python API: | ||
| - Core: reference/core.md # MOVED from core.md | ||
| - Client Types: reference/client-types.md # NEW - EnvClient, StepResult, etc. | ||
| - Server Types: reference/server-types.md # NEW - Environment, Action, Observation | ||
| - CLI Reference: reference/cli.md # MOVED from cli.md | ||
| - Configuration: | ||
| - openenv.yaml: reference/openenv-yaml.md # NEW - Manifest format reference | ||
| - Environment Variables: reference/env-vars.md # NEW | ||
|
|
||
| - Community: | ||
| - Contributing: contributing.md # LINK to CONTRIBUTING.md | ||
| - RFCs: rfcs.md # NEW - Link to rfcs/ | ||
| - Partners & Supporters: partners.md # NEW - Extract from README | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## New Content Needed | ||
|
|
||
| ### Priority 1: Core Conceptual Content (Write First) | ||
|
|
||
| | Page | Purpose | Source | | ||
| |------|---------|--------| | ||
| | `introduction.md` | What is OpenEnv? Problem it solves, key value props | Extract from index.md + README.md | |
Contributor
There was a problem hiding this comment.
Planning artifacts committed to repository root. Both docs_reorganization_proposal.md and docs_audit.csv appear to be working documents used to plan this reorganization. These should not be committed to the repository root as they create clutter and confusion for contributors who discover them while browsing or cloning.
Consider one of the following:
- Remove them (since the reorganization is complete)
- Move them to an internal directory like
.claude/ordocs/_internal/ - Convert to official documentation as ADR or RFC if the decisions are worth preserving long-term
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs_reorganization_proposal.md
Line: 1-100
Comment:
Planning artifacts committed to repository root. Both `docs_reorganization_proposal.md` and `docs_audit.csv` appear to be working documents used to plan this reorganization. These should not be committed to the repository root as they create clutter and confusion for contributors who discover them while browsing or cloning.
Consider one of the following:
1. **Remove them** (since the reorganization is complete)
2. **Move them** to an internal directory like `.claude/` or `docs/_internal/`
3. **Convert to official documentation** as ADR or RFC if the decisions are worth preserving long-term
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganized the docs into a content-centric structure, fixed broken links and formatting issues across guides and tutorials, and merged in the latest changes from main.
Type of Change
Alignment Checklist
Before submitting, verify:
.claude/docs/PRINCIPLES.mdand this PR aligns with our principles.claude/docs/INVARIANTS.mdand no invariants are violated/pre-submit-pr(orbash .claude/hooks/lint.shand tests) and addressed all issuesRFC Status
Test Plan
Claude Code Review