Skip to content

docs: document the body and HTML opt-ins in the API reference - #13

Merged
artiom merged 1 commit into
mainfrom
docs/reference-opt-in-notes
Nov 16, 2026
Merged

artiom merged 1 commit into
mainfrom
docs/reference-opt-in-notes

Conversation

@Gikoskos

@Gikoskos Gikoskos commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

The generated API reference left out two things that 0.3.0 users need to know:

  • inner_html and outer_html need html=True on the query. The async ElementHandle properties say so in their docstrings, but the reference generator ignored property docstrings, and the sync properties had none. The reference showed only Type: str | None.
  • body_encoding=True fetches the body by itself. response() said this in a second paragraph, and the generator keeps only the first paragraph, so the reference read "fetch bodies only with body=True".

Changes:

  • scripts/codegen/emit_docs.py: write each property's docstring summary under its Type: line.
  • response() (async and sync): one-paragraph docstring: "List responses. Bodies are fetched only with body=True or body_encoding=True; body_encoding=True also adds the base64Encoded flag."
  • Sync ElementHandle.inner_html / outer_html: the same docstrings as the async properties.
  • query_selector / query_selector_all docs: add that reading inner_html or outer_html without html=True raises BAPValueError. _page_generated.py was regenerated from this.
  • tests/test_codegen_docs.py: check that all three notes appear in the generated pages.

Only docstrings and the docs generator change. Runtime behavior does not.

Related issues

None.

Type of change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that changes existing behavior)
  • Documentation only
  • Chore / tooling

Checklist

  • ruff format --check .
  • ruff check .
  • mypy
  • pytest -m "not e2e" (347 passed)
  • python scripts/codegen.py leaves no diff
  • Tests added or updated
  • Docs updated
  • Did not hand-edit generated files or AUTOGEN regions
  • Title follows Conventional Commits (type: summary)
  • Title, description and commits contain no internal ticket IDs or internal links (see CONTRIBUTING.md › Public repository rules)

Notes for reviewers

The docs site's reference is updated from this branch in a separate docs change.

🤖 Generated with Claude Code


Devin Review

Summary by CodeRabbit

  • Documentation
    • Clarified that element HTML properties require html=True when querying elements; accessing them otherwise raises BAPValueError.
    • Clarified that response bodies are fetched with body=True or body_encoding=True, and that body_encoding=True adds a base64-encoding flag.
    • Generated property references now include a brief summary when available.

The generated reference dropped property docstrings and kept only the
first paragraph of response(), so it never said that inner_html and
outer_html need html=True, or that body_encoding=True also fetches the
body. Emit property docstrings, fold the body_encoding note into the
response() summary, give the sync ElementHandle HTML properties the same
docstrings as the async ones, and say that reading the HTML without
html=True raises BAPValueError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Gikoskos
Gikoskos requested a review from a team as a code owner November 16, 2026 14:10
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The API documentation now describes when element HTML and response bodies are available, and when accessing element HTML raises BAPValueError. The documentation generator now includes nonempty first-paragraph summaries for public properties.

Changes

API documentation

Layer / File(s) Summary
Document API behavior and render property summaries
scripts/codegen/config/docs.py, scripts/codegen/emit_docs.py, src/browserless_bap/_page_generated.py, src/browserless_bap/page.py, src/browserless_bap/sync_api/_page_generated.py, src/browserless_bap/sync_api/element_handle.py, src/browserless_bap/sync_api/page.py, tests/test_codegen_docs.py
The query documentation states that reading inner_html or outer_html without html=True raises BAPValueError. The response documentation describes when bodies are fetched and the base64Encoded flag. The generator adds nonempty first-paragraph summaries to public property entries. Tests assert the generated documentation includes these details.

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

Change: Other

Suggested reviewers: artiom, ahmedamien

Merge Risk: Minimal · up to de709

This PR only clarifies the API reference for HTML and response-body options. It does not change runtime behavior, and no actionable merge risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the documentation change: the API reference now documents the body and HTML opt-ins. The raw summary confirms the changes cover the html=True requirement for inner_html/outer_html and …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the documentation change: the API reference now documents the body and HTML opt-ins. The raw summary confirms the changes cover the html=True requirement for inner_html/outer_html and the body_encoding=True behavior for response(), with the generator and tests updated to match. The title is specific and matches the main change.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

A rabbit reads the docs at dawn
“Use html=True,” it hops along
For bodies, flags are clearly shown
Property summaries now appear
The rabbit nibbles, pleased and clear.

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Team
  • Run ID: 98a1e493-1738-45d1-afa7-eb91a061d6b4
Commits

Reviewing files that changed from the base of the PR and between 5aeb831 and de7090f.

Files selected for processing: 8

  • scripts/codegen/config/docs.py
  • scripts/codegen/emit_docs.py
  • src/browserless_bap/_page_generated.py
  • src/browserless_bap/page.py
  • src/browserless_bap/sync_api/_page_generated.py
  • src/browserless_bap/sync_api/element_handle.py
  • src/browserless_bap/sync_api/page.py
  • tests/test_codegen_docs.py

Included review availability: This review used your included allowance. 7 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@artiom
artiom merged commit 3d88d3f into main Nov 16, 2026
18 checks passed
@artiom
artiom deleted the docs/reference-opt-in-notes branch November 16, 2026 16:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants