Add solver documentation guide

[jcarius-nv]

Description

Add a top-level Solvers documentation section so solver selection, feature comparisons, and backend-specific guidance are easier to discover.

• Move the solver overview, feature matrix, contact-material support, joint support, and differentiability guidance out of the generated API page and into a dedicated Solvers overview.
• Move the MuJoCo guide under Solvers and add a concise Kamino guide with purpose, selection context, experimental status, API links, and examples.
• Expose Overview, MuJoCo, and Kamino consistently in the sidebar, and link Isaac Lab directly under Further Reading.
• Preserve the former Integrations URLs with redirects or a compatibility landing page, and update repository references to the new canonical paths.
• Keep a concise, source-friendly solver taxonomy and local/hosted guide pointers in the newton.solvers module docstring.

This is a documentation-only change; it does not change solver behavior or public APIs.

Closes #2257

Content migration and discoverability

This PR reorganizes existing documentation rather than removing it:

• The narrative previously maintained in newton/solvers.py—including the solver workflow, feature matrix, contact-material support, joint-feature support, and differentiability guidance—moves to docs/solvers/index.rst.
• docs/integrations/mujoco.rst moves to docs/solvers/mujoco.rst. Its content is unchanged except for correcting the inaccurate statement that use_mujoco_contacts=False is the default.
• docs/integrations/isaac-lab.rst moves to docs/lab/isaac-lab.rst.
• docs/api/newton_solvers.rst becomes API-focused; its module declaration, submodule navigation, and solver autosummary remain unchanged.
• Legacy Integrations URLs remain useful through redirects or a compatibility landing page.

A key design consideration was whether moving the large newton.solvers module docstring would make the information harder to discover for source-first users and coding agents. To preserve that discoverability without maintaining duplicate feature matrices, the shortened module docstring now:

• summarizes the available solver categories;
• names the repository-local source, docs/solvers/index.rst;
• links to the hosted Solvers guide for installed-wheel users; and
• describes the comparisons available in the guide.

The detailed information therefore has one authoritative home, while remaining reachable from the source module, generated API page, top-level documentation sidebar, overview page, and hosted documentation.

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• CHANGELOG.md has been updated (if user-facing change)

Test plan

uv run docs/generate_api.py
uv run --extra docs --extra sim sphinx-build -E -a -j auto -W -b html docs docs/_build/html
uv run --extra docs --extra sim sphinx-build -E -a -j auto -W -b doctest docs docs/_build/doctest
/usr/bin/env UV_CACHE_DIR=/tmp/newton-uv-cache UV_TOOL_DIR=/tmp/newton-uv-tools PRE_COMMIT_HOME=/tmp/newton-pre-commit-cache uvx --python 3.12 pre-commit run -a

The strict HTML build passed, all 85 doctests passed, and the rendered sidebar and legacy URL outputs were inspected directly.

Summary by CodeRabbit

• New Features
  • Added the Solvers documentation guide with solver overviews, capability comparison tables, and example workflows.
  • Added dedicated documentation pages for the MuJoCo solver, the experimental Kamino solver, and the Isaac Lab integration.
• Documentation
  • Updated navigation and cross-references to point to the new Solvers guide and reorganized integration/lab pages.
  • Added redirect notices/stubs for moved guides so readers land on the latest locations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 95378957-490e-41c5-b2c2-116dfdfdba40

📥 Commits

Reviewing files that changed from the base of the PR and between 64b5c06 and a815f00.

📒 Files selected for processing (7)

• docs/api/newton_solvers.rst
• docs/conf.py
• docs/solvers/index.rst
• docs/solvers/kamino.rst
• docs/solvers/mujoco.rst
• docs/tutorials/00_introduction.ipynb
• newton/solvers.py

✅ Files skipped from review due to trivial changes (4)

• docs/solvers/kamino.rst
• docs/tutorials/00_introduction.ipynb
• newton/solvers.py
• docs/solvers/mujoco.rst

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/api/newton_solvers.rst
• docs/solvers/index.rst

---

📝 Walkthrough

Walkthrough

This PR adds a Solvers guide, adds a new Isaac Lab page under Lab, redirects old Integrations pages to the new locations, and updates documentation links plus inline MuJoCo references to the reorganized doc paths.

Changes

Documentation reorganization

Layer / File(s)	Summary
Solvers guide index and legacy summaries docs/solvers/index.rst, docs/api/newton_solvers.rst, newton/solvers.py	Adds the Solvers guide index content and shortens the legacy solver module/API documentation to point readers to the new guide.
MuJoCo solver guide docs/solvers/mujoco.rst	Adds the MuJoCo solver documentation page with backend mapping, contact and joint conversions, collision behavior, option resolution, import/export rules, caveats, and code entry points.
Kamino solver guide docs/solvers/kamino.rst	Adds the Kamino solver documentation page with scope text, experimental status, and links to the API reference and examples.
Lab page and integration redirects docs/lab/isaac-lab.rst, docs/integrations/index.rst, docs/integrations/isaac-lab.rst, docs/integrations/mujoco.rst, CHANGELOG.md	Adds the new Isaac Lab page and replaces the old integrations index and solver pages with moved-page notices and redirect stubs.
Docs navigation and cross-references docs/index.rst, docs/guide/overview.rst, docs/guide/installation.rst, docs/concepts/collisions.rst, docs/conf.py, docs/tutorials/00_introduction.ipynb	Updates the docs landing page, guide links, collision docs reference, Sphinx sidebar configuration, and tutorial link targets to use the reorganized solver and lab paths.
MuJoCo doc link updates in code comments newton/_src/solvers/mujoco/kernels.py, newton/_src/solvers/mujoco/solver_mujoco.py, newton/_src/usd/schemas.py, newton/_src/utils/import_mjcf.py	Updates inline comments, warning text, and schema references in MuJoCo-related source files to point to the new solver guide documentation.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• newton-physics/newton#2574: Overlaps with the MuJoCo documentation move and redirect stub changes.
• newton-physics/newton#3016: Also updates solver integration content in docs/api/newton_solvers.rst and newton/solvers.py.
• newton-physics/newton#3011: Touches the same solver overview and cross-link surfaces in docs/guide/overview.rst.

Suggested labels: docs

Suggested reviewers: adenzler-nvidia, eric-heiden

🚥 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 is concise and accurately summarizes the main change: adding a solver documentation guide.
Linked Issues check	✅ Passed	The PR adds a top-level Solvers guide, dedicated MuJoCo and Kamino pages, and renames Integrations to Lab as requested.
Out of Scope Changes check	✅ Passed	The changes stay within documentation reorganization and navigation updates, with no clear unrelated code or feature work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/solvers/index.rst`:
- Around line 145-146: The MuJoCo footnote wording is reversed and should match
the detailed docs: update the note in the solver overview so it states that
MuJoCo uses its own collision pipeline by default, and that setting
use_mujoco_contacts to False switches to Newton contacts. Keep the change in the
same note near the MuJoCo solver entry so the overview aligns with the dedicated
MuJoCo guide.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 739e56d4-2ca3-4d8b-8eda-296ede187aee

📥 Commits

Reviewing files that changed from the base of the PR and between 842dc6f and c169356.

📒 Files selected for processing (18)

• CHANGELOG.md
• docs/api/newton_solvers.rst
• docs/concepts/collisions.rst
• docs/guide/installation.rst
• docs/guide/overview.rst
• docs/index.rst
• docs/integrations/index.rst
• docs/integrations/isaac-lab.rst
• docs/integrations/mujoco.rst
• docs/lab/isaac-lab.rst
• docs/solvers/index.rst
• docs/solvers/kamino.rst
• docs/solvers/mujoco.rst
• newton/_src/solvers/mujoco/kernels.py
• newton/_src/solvers/mujoco/solver_mujoco.py
• newton/_src/usd/schemas.py
• newton/_src/utils/import_mjcf.py
• newton/solvers.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[adenzler-nvidia]

The migration itself checks out: the moves are verbatim, the use_mujoco_contacts correction matches the code default, and the hand-edited docs/api/newton_solvers.rst matches what docs/generate_api.py regenerates. Two referrers outside this diff still point at the old location, though:

• docs/tutorials/00_introduction.ipynb links to https://newton-physics.github.io/newton/stable/api/newton_solvers.html#supported-features, but this PR removes the Supported Features section from that page. The redirect stubs can't cover this case since the page itself still exists, so tutorial readers will land on the slimmed-down API page with no feature table. The link should target the new anchor on /solvers/index.html (the PR already adds an explicit .. _Supported Features: label there).

• docs/conf.py's secondary_sidebar_items override still disables the right-hand page TOC only for api/newton_solvers, with the comment citing "several wide comparison tables" — but those tables moved to solvers/index. As is, the new overview renders the wide feature/joint-support tables with the secondary sidebar eating content width (the problem the override was added to fix), while the now-slim API page needlessly loses its page TOC.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[jcarius-nv]

Addressed the remaining review-summary findings in a815f00:

• Updated the introductory tutorial's solver-feature link to the new Solvers overview.
• Moved the wide-table secondary-sidebar override from the slim API page to the Solvers overview.

The four inline threads addressed by the same commit have also been replied to and resolved.

[adenzler-nvidia]

LGTM