Replace local sphinx_mintlify with PyPI package

[giordano-lucas]

Summary

• Published sphinx-mintlify to PyPI and replaced the local editable install (uv pip install -e ../sphinx_mintlify) with a proper dev dependency
• Removed the local install step from the docs-sdk Makefile target
• Added docs-sdk-generate pre-commit hook that regenerates SDK reference docs when SDK source files or Sphinx config change, ensuring docs stay in sync

Test plan

• sphinx-mintlify published and installable from PyPI (pip install sphinx-mintlify==0.1.0)
• uv lock resolves the package successfully
• Pre-commit hooks pass
• Run make docs-sdk to verify SDK docs generate correctly without local package
• Modify an SDK docstring and verify the pre-commit hook catches the drift

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores

  • Added a pre-commit hook to run automated SDK docs generation.
  • Simplified the docs build target and adjusted build cleanup.

• Documentation

  • Added a new RootModel reference page.
  • Standardized and clarified several SDK type annotations and callback signatures.
  • Added a dev dependency to support enhanced documentation formatting.

Greptile Summary

This PR migrates sphinx-mintlify from a local editable install (uv pip install -e ../sphinx_mintlify) to a proper PyPI package (sphinx-mintlify==0.1.0) pinned in dev dependencies, and adds a docs-sdk-generate pre-commit hook to keep SDK reference docs in sync with source changes. The dependency migration and lock file look correct. The only notable concern is that check-sdk-docs is ordered before docs-sdk-generate in .pre-commit-config.yaml, which can require two commit attempts when SDK source and docs are both out of sync.

Confidence Score: 5/5

Safe to merge — all findings are P2 style/workflow suggestions with no correctness or data-integrity risk.

The dependency migration is straightforward and the lock file hashes are verified. Both comments are P2: hook ordering is a developer UX concern (not a broken workflow), and the missing smoke test is a best-practice note for a tooling-only change.

.pre-commit-config.yaml — hook ordering between check-sdk-docs and docs-sdk-generate is worth revisiting.

Important Files Changed

Filename	Overview
.pre-commit-config.yaml	Adds docs-sdk-generate hook that runs make docs-sdk on SDK source/conf changes; hook ordering places it after check-sdk-docs, which can cause a two-step commit cycle when docs are stale.
makefile	Removes the local editable install step (uv pip install -e ../sphinx_mintlify) from docs-sdk target; now relies on the PyPI package in dev dependencies.
pyproject.toml	Adds sphinx-mintlify>=0.1.0 as a dev dependency, replacing the previous local editable install.
uv.lock	Locks sphinx-mintlify 0.1.0 from PyPI with verified hashes; dependencies (docutils, sphinx, typing-extensions) look appropriate.
docs/src/sdk-reference/remotesession/init.mdx	Auto-generated file updated to add vault_id parameter field, consistent with surrounding ParamField patterns.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: .pre-commit-config.yaml
Line: 73-78

Comment:
**Hook ordering may produce confusing two-step commit cycle**

`check-sdk-docs` (line 66) runs before `docs-sdk-generate` (line 73). When SDK source files change and the generated docs are stale, `check-sdk-docs` can fail first, then `docs-sdk-generate` regenerates the docs and causes a file-modification failure — requiring the developer to restage and commit twice before both hooks pass.

Swapping the two hooks (generate first, then check) would let regeneration happen before the check runs, reducing the typical workflow to a single extra commit instead of two.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: pyproject.toml
Line: 73

Comment:
**No tests added**

This PR introduces a new pre-commit hook that runs `make docs-sdk` automatically. There are no tests verifying that the hook triggers correctly or that `make docs-sdk` produces consistent output with the published PyPI package. While this is primarily a tooling/dependency migration, a smoke test (e.g., running `make docs-sdk` in CI against the pinned version) would confirm the PyPI package behaves identically to the previous local editable install.

**Context Used:** # Test guidelines
- Add a comment if the PR does n... ([source](https://app.greptile.com/review/custom-context?memory=instruction-0))

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "Replace local sphinx_mintlify install wi..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

Context used:

• Context used - # Test guidelines
• Add a comment if the PR does n... (source)

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 71a9c8de-e921-43ae-8213-e039ff822f9a

📥 Commits

Reviewing files that changed from the base of the PR and between d3a30bb and 497aeef.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (12)

• .pre-commit-config.yaml
• docs/src/sdk-reference/manual/session.mdx
• docs/src/sdk-reference/misc/captchasolveaction.mdx
• docs/src/sdk-reference/misc/formfillaction.mdx
• docs/src/sdk-reference/misc/rootmodel.mdx
• docs/src/sdk-reference/misc/structureddata.mdx
• docs/src/sdk-reference/misc/websocketservice.mdx
• docs/src/sdk-reference/nottefunction/run.mdx
• docs/src/sdk-reference/nottevault/patch_structured_completion.mdx
• docs/src/sdk-reference/remotesession/__init__.mdx
• makefile
• pyproject.toml

💤 Files with no reviewable changes (1)

• makefile

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

• docs/src/sdk-reference/remotesession/init.mdx
• docs/src/sdk-reference/misc/rootmodel.mdx
• .pre-commit-config.yaml
• docs/src/sdk-reference/manual/session.mdx
• docs/src/sdk-reference/nottevault/patch_structured_completion.mdx
• pyproject.toml
• docs/src/sdk-reference/nottefunction/run.mdx
• docs/src/sdk-reference/misc/structureddata.mdx
• docs/src/sdk-reference/misc/formfillaction.mdx
• docs/src/sdk-reference/misc/captchasolveaction.mdx
• docs/src/sdk-reference/misc/websocketservice.mdx

---

Walkthrough

Added a local pre-commit hook docs-sdk-generate to run make docs-sdk (language: system, pass_filenames: false) and trigger on changes under packages/notte-sdk/src/ or docs/sphinx/conf.py. Removed an editable install step for sphinx_mintlify from the docs-sdk Makefile target. Added sphinx-mintlify>=0.1.0 to the [dependency-groups].dev section in pyproject.toml. Updated multiple SDK reference MDX files to adjust type annotations/formatting (quoting literals, using | None, refining callables) and added a new rootmodel.mdx documentation page describing a root field.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: replacing a local sphinx_mintlify package with the official PyPI version.
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
• Commit unit tests in branch t3code/release-docs-package-to-pypi

---

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

[2027-evals]

✅ Eval complete for commit 48d67dd

URL	Mapping
docs.notte.cc	→ notte-t3code-release-docs-package-to-pypi.mintlify.app

Ran evals with prompts:

📈 +4.6 pts · Getting Started — C (72.3/100) from C (67.7) · View metrics

Prompt text:

Use Notte to run a headless browser session. Follow the quickstart at https://notte.cc/ to set up a project that:

1. Creates a cloud browser session
2. Connects to it using Playwright, Puppeteer, or the Notte SDK
3. Navigates to https://news.ycombinator.com
4. Extracts the titles of the top 5 stories
5. Prints them to stdout

Verdict:

Notte's SDK and cloud browser infrastructure work well, but documentation gaps around auth configuration and a broken SDK reference page created unnecessary friction that a polished quickstart could eliminate.

Friction points:

• 🔴 The quickstart does not explicitly name the NOTTE_API_KEY environment variable — The quickstart does not explicitly name the NOTTE_API_KEY environment variable — the agent had to inspect SDK source code to discover the exact env var name and that NotteClient() reads it automatically.
• 🔴 docs — docs.notte.cc/sdk-reference/client returned a 404, breaking the API reference link that would have answered key questions about NotteClient constructor parameters.
• 🟡 The canonical documentation URL is fragmented between notte — The canonical documentation URL is fragmented between notte.cc, docs.notte.cc, and a mintlify staging subdomain — creating ambiguity about where to find authoritative content.
• 🟡 The CDP URL retrieval method (session — The CDP URL retrieval method (session.cdp_url()) is not clearly documented in the quickstart; the agent inferred it from the sessions concepts page after additional lookups.

Result: C (72.3/100)

delta vs baseline: +4.6 pts

Dimension	Baseline	This PR
Setup Friction	72	86
Speed	60	78
Efficiency	44	46
Error Recovery	100	93
Doc Quality	70	60

Stats: 2m 35s · 22 tool calls · 1 error · 1 interruption · $0.95

View report → · View trace →

---

Evaluating agent experience using 2027.dev · View dashboard

[coderabbitai]

🧹 Nitpick comments (1)

pyproject.toml (1)

73-73: Pin sphinx-mintlify exactly for reproducible docs builds.

Line 73 uses a floating lower bound (>=0.1.0). Keeping it ranged can cause docs drift across environments as new plugin versions are released. The locked version is currently 0.1.0, so pinning exactly would maintain the intended behavior.

Proposed change

-    "sphinx-mintlify>=0.1.0",
+    "sphinx-mintlify==0.1.0",

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pyproject.toml` at line 73, Change the dependency specification for
sphinx-mintlify from a ranged requirement to an exact pin: replace
"sphinx-mintlify>=0.1.0" with an exact version "sphinx-mintlify==0.1.0" in the
pyproject.toml dependencies so docs builds remain reproducible; ensure you
update the same dependency entry where "sphinx-mintlify>=0.1.0" appears.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@pyproject.toml`:
- Line 73: Change the dependency specification for sphinx-mintlify from a ranged
requirement to an exact pin: replace "sphinx-mintlify>=0.1.0" with an exact
version "sphinx-mintlify==0.1.0" in the pyproject.toml dependencies so docs
builds remain reproducible; ensure you update the same dependency entry where
"sphinx-mintlify>=0.1.0" appears.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 751d147b-8c9b-4abb-a325-e2d4b1351beb

📥 Commits

Reviewing files that changed from the base of the PR and between 377fbb0 and c340251.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• .pre-commit-config.yaml
• docs/src/sdk-reference/remotesession/__init__.mdx
• makefile
• pyproject.toml

💤 Files with no reviewable changes (1)

• makefile