fix: address documentation and tooling drift (#163)

[ChrisJr404]

Closes #163.

1. README + docs dev-install command

pip install -e '.[dev]' stopped working when dev deps moved from [project.optional-dependencies] into the dev uv dependency group (current pyproject.toml). Both README.md and docs/getting-started.md now point at make install, which is what CONTRIBUTING.md and the Makefile already canonicalize to (uv sync + pre-commit install).

docs/mcp-integration.md still uses pip install -e '.[mcp-docker]' — left alone because mcp-docker is a real [project.optional-dependencies] extra, so that command still works.

2. custom-images.md in nav

Added under User Guide between Container Backends and Supported Languages. The file already has substantive content covering custom images, Dockerfiles, and pre-installed libraries, so merging into another page would have lost structure. One-line change in mkdocs.yml.

3. container-pooling.md stale anchors

Two distinct issues:

• API Reference section linked to api-reference.md#llm_sandbox.pool.{base.ContainerPoolManager,config.PoolConfig,session.PooledSandboxSession,factory.create_pool_manager}, but docs/api-reference.md had no ::: directives for those modules — anchors never existed. Added a Container Pooling section to api-reference.md with the four mkdocstrings entries; anchors now resolve.
• Related Documentation pointed at configuration.md#performance-optimization, which doesn't exist. Repointed at configuration.md#container-pooling-configuration (real anchor, more relevant to the link text anyway).

4. Fail CI on doc warnings

Already done — .github/workflows/main.yml check-docs job runs uv run mkdocs build -s and Makefile exposes the same as make docs-test. No workflow changes needed.

5. mkdocs build -s warning count

	before	after
mkdocs build -s warnings	6	0

Six pre-existing INFO-level drift messages (1 unlisted nav page + 5 unresolved anchor links from container-pooling.md) — all gone:

$ uv run mkdocs build -s
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: .../site
INFO    -  Documentation built in 3.39 seconds

Diffstat

 README.md                 |  7 ++++++-
 docs/api-reference.md     | 20 ++++++++++++++++++++
 docs/container-pooling.md |  2 +-
 docs/getting-started.md   |  6 ++++--
 mkdocs.yml                |  1 +
 5 files changed, 32 insertions(+), 4 deletions(-)

Did not touch docs/security.md (recently rewritten in #165).

Summary by CodeRabbit

Documentation

• Updated development setup instructions to use uv and make install instead of pip.
• Added Container Pooling section to API reference documenting pooled execution capabilities.
• Added new "Custom Images" documentation page to user guide.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e04e6cfd-02ec-44bc-8e77-b640b6e25604

📥 Commits

Reviewing files that changed from the base of the PR and between 5f7478d and 6378047.

📒 Files selected for processing (5)

• README.md
• docs/api-reference.md
• docs/container-pooling.md
• docs/getting-started.md
• mkdocs.yml

---

📝 Walkthrough

Walkthrough

This pull request resolves documentation and tooling drift by updating development setup instructions across README and docs to reflect the uv dependency group workflow, adding missing "Container Pooling" API documentation, registering the "Custom Images" page in navigation, and fixing stale cross-references.

Changes

Documentation and Tooling Alignment

Layer / File(s)	Summary
Development Setup Instructions README.md, docs/getting-started.md	Development installation instructions updated from pip install -e '.[dev]' to uv dependency groups via make install command, with reference to the contributing workflow.
API Documentation docs/api-reference.md	New "Container Pooling" section added, documenting ContainerPoolManager, PoolConfig, PooledSandboxSession, and create_pool_manager factory under llm_sandbox.pool namespace.
Navigation & Cross-references mkdocs.yml, docs/container-pooling.md	"Custom Images" page registered in MkDocs navigation; stale anchor link updated from configuration.md#performance-optimization to configuration.md#container-pooling-configuration.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

documentation, size:XS

---

🐰 A hop through the docs, so tidy and neat,
With dev tools now dancing in rhythm and beat,
No more drift to confuse a new friend,
Just clear paths from start to the end. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: address documentation and tooling drift (#163)' clearly and specifically identifies the main change—addressing documentation and tooling drift issues—and references the related issue.
Linked Issues check	✅ Passed	All coding-related requirements from issue #163 are met: README and docs updated for uv workflow [#163], custom-images.md added to MkDocs nav [#163], container-pooling.md anchors fixed with new API reference section [#163], and mkdocs build -s warnings resolved from 6 to 0.
Out of Scope Changes check	✅ Passed	All changes directly address requirements in #163: documentation and tooling updates, MkDocs navigation addition, and API reference documentation. No unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[vndee]

Checked both claims and they hold.

dev lives in [dependency-groups], not [project.optional-dependencies], so pip install -e '.[dev]' was never going to work — pip reports the extra doesn't exist. Anyone following the README to set up a dev environment hit that.

The pooling anchors are genuinely missing too. docs/api-reference.md has zero llm_sandbox.pool entries right now, which is why mkdocs build has been logging these:

Doc file 'container-pooling.md' contains a link
'api-reference.md#llm_sandbox.pool.session.PooledSandboxSession',
but the doc 'api-reference.md' does not contain an anchor

I'd seen those scroll past and not chased them. Good catch.

Small and correct — merging this one.