docs: complete the documentation site and slim the README#208
Merged
Conversation
Build the docs site out into a Getting Started page, an eleven page guide, and a four page reference, modeled on the two tier onboarding and uniform page template used by hikari-lightbulb. The guide covers configuration, drivers, model types, writing queries, enums, type overrides, converters, working with JSON, docstrings, SQLite type conversion, and naming. The reference documents every configuration option and config object schema, the SQL to Python type mappings for both engines, and per driver feature support. Generated code examples are taken verbatim from the committed test fixtures. Slim the README down to the example config plus a feature list that links into the site, since those sections now live there.
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR condenses the README, reorganizes hosted documentation into Guide and Reference sections, and adds pages covering configuration, generated-code behavior, type conversion, drivers, query generation, and feature support. ChangesDocumentation reorganization
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
Contributor
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 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/content/docs/getting-started.md`:
- Around line 59-62: Replace the root-relative documentation links with
base-path-aware relative links or Hugo ref/relref links. Update
docs/content/docs/getting-started.md:59-62,
docs/content/docs/guide/_index.md:30-31,
docs/content/docs/reference/_index.md:9-10,
docs/content/docs/guide/configuration.md:8-10,
docs/content/docs/reference/configuration-options.md:8-10,
docs/content/docs/reference/type-mappings.md:8-10, and
docs/content/docs/reference/feature-support.md:29-30; preserve each link’s
existing destination and displayed text.
In `@docs/content/docs/guide/converters.md`:
- Around line 76-80: Update the wire-type sentence in the converter
documentation to say that `to_db` must return a type that the driver accepts,
replacing the grammatically incorrect “return one the driver accepts” wording
while leaving the surrounding guidance unchanged.
In `@docs/content/docs/guide/drivers.md`:
- Around line 56-60: Update the SQLite warning callout in the drivers
documentation to make the PARSE_DECLTYPES requirement conditional: state that
both SQLite drivers require it only when using generated type conversions, while
preserving the existing explanation of generated adapters and converters.
- Around line 41-42: Update both examples to import sqlite3 and pass
sqlite3.PARSE_DECLTYPES instead of aiosqlite.PARSE_DECLTYPES:
docs/content/docs/guide/drivers.md lines 41-42 and
docs/content/docs/guide/sqlite-type-conversion.md lines 26-30. Preserve the
existing connection examples and query behavior.
In `@docs/content/docs/guide/sqlite-type-conversion.md`:
- Around line 62-65: Update the callout describing sqlite3.register_converter to
state that registrations are process-global and that limiting registrations to a
module’s needs only avoids unnecessary conversions; do not imply this prevents
modules from affecting one another when they use the same SQL type key.
In `@docs/content/docs/guide/working-with-json.md`:
- Around line 206-218: Update the alternative JSON examples around
encode_preferences and decode_preferences so each tab uses a model type matching
its serialization API: define dataclass and Pydantic Preferences variants where
needed, or replace the APIs with ones compatible with the existing
msgspec.Struct. Ensure decoding reconstructs nested Theme objects rather than
leaving them as raw dictionaries.
In `@docs/content/docs/guide/writing-queries.md`:
- Around line 125-127: Update the query_parameter_limit description in the
query-writing guide to state that parameter bundling applies only when the
option is configured to a non-negative value; unset or negative values must
never bundle parameters. Keep the existing explanation of the generated
<Name>Params object and :copyfrom behavior, matching the semantics in the
configuration options documentation.
In `@docs/content/docs/reference/type-mappings.md`:
- Line 18: Update the Nullable type-mapping documentation entry to remove the
leading space inside the inline code span, changing the displayed type from ` |
None` to `| None`.
🪄 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.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 92d449f3-09b2-423d-bb77-75d9835a6af2
📒 Files selected for processing (20)
README.mddocs/content/docs/_index.mddocs/content/docs/converters.mddocs/content/docs/getting-started.mddocs/content/docs/guide/_index.mddocs/content/docs/guide/configuration.mddocs/content/docs/guide/converters.mddocs/content/docs/guide/docstrings.mddocs/content/docs/guide/drivers.mddocs/content/docs/guide/enums.mddocs/content/docs/guide/model-types.mddocs/content/docs/guide/naming.mddocs/content/docs/guide/sqlite-type-conversion.mddocs/content/docs/guide/type-overrides.mddocs/content/docs/guide/working-with-json.mddocs/content/docs/guide/writing-queries.mddocs/content/docs/reference/_index.mddocs/content/docs/reference/configuration-options.mddocs/content/docs/reference/feature-support.mddocs/content/docs/reference/type-mappings.md
💤 Files with no reviewable changes (1)
- docs/content/docs/converters.md
aiosqlite does not re-export PARSE_DECLTYPES, so the connection examples raised AttributeError. Use sqlite3.PARSE_DECLTYPES with aiosqlite.connect, matching how the test suite opens those connections, and import sqlite3 in both examples. Scope the PARSE_DECLTYPES requirement to schemas that actually generate type conversions, and correct the register_converter note: registration is process-global, so limiting it per module avoids unused conversions but does not isolate modules from each other. Make the alternative JSON examples self consistent by defining the model with the same library the converter uses, and rebuild nested objects in the stdlib decoder. State that query_parameter_limit only bundles when set to a non-negative value, and fix two wording and formatting nits.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/content/docs/guide/drivers.md (1)
59-61: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winScope the PARSE_DECLTYPES requirement to returned-column converters.
The related SQLite guide states that parameters use adapters while returned columns use converters.
detect_types=sqlite3.PARSE_DECLTYPESis required for the latter, not for every generated adapter registration; otherwise this warning makes adapter-only write paths appear to require unnecessary connection settings.Suggested wording
- Whenever the generated code registers type conversions - which it does for - `date`, `datetime`/`timestamp`, `decimal`, `bool`, and `blob` columns - both + Whenever the generated code registers declared-type converters for returned + `date`, `datetime`/`timestamp`, `decimal`, `bool`, and `blob` columns, both🤖 Prompt for 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. In `@docs/content/docs/guide/drivers.md` around lines 59 - 61, Revise the statement in the SQLite drivers guidance to scope detect_types=sqlite3.PARSE_DECLTYPES specifically to generated converters for returned columns, not all type conversion or adapter registrations. Preserve the listed column types while clarifying that adapter-only parameter paths do not require this connection setting.
🤖 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/content/docs/guide/working-with-json.md`:
- Around line 228-229: Add a blank line between the closing standard-library
code fence and the following prose in the documented JSON guide, preserving the
existing text and code-fence content.
---
Duplicate comments:
In `@docs/content/docs/guide/drivers.md`:
- Around line 59-61: Revise the statement in the SQLite drivers guidance to
scope detect_types=sqlite3.PARSE_DECLTYPES specifically to generated converters
for returned columns, not all type conversion or adapter registrations. Preserve
the listed column types while clarifying that adapter-only parameter paths do
not require this connection setting.
🪄 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.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 6193eb80-a849-4184-8c81-3d4d80100671
📒 Files selected for processing (6)
docs/content/docs/guide/converters.mddocs/content/docs/guide/drivers.mddocs/content/docs/guide/sqlite-type-conversion.mddocs/content/docs/guide/working-with-json.mddocs/content/docs/guide/writing-queries.mddocs/content/docs/reference/type-mappings.md
detect_types governs converters, which decode returned columns, not the adapters that encode parameters. Scope the drivers callout to queries that return date, datetime/timestamp, decimal, bool, or blob columns, and say outright that parameter adapters work without the setting. Separate the tab commentary from the preceding code fence with a blank line throughout the JSON and model type pages, and drop the roadmap link from the README.
Carry the page from install and configuration through to a first working query: a schema, an annotated query file, the generated model and query functions, and the call sites that use them. Every driver specific block is a synced tab group, so picking asyncpg, aiosqlite or sqlite3 once switches the whole page. That includes how a :many result is consumed, which differs between the async drivers, where the result is awaited or iterated, and sqlite3, where it is called.
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
Give the documentation landing page something to land on: icons on the section cards, a short SQL to Python showcase, a grid linking every feature page, a support summary table, and cards for issues, Discord and the changelog. Point the home page feature cards at the guide pages they describe, now that those pages exist. Card links are relative, because the card shortcode does not resolve a leading slash against the site base path the way markdown links do.
The home page stopped at the feature grid and left the rest of the screen empty. Follow it with the two things a visitor actually wants: what the plugin produces, shown as an annotated query next to the typed function and model it generates, and how to start, shown as the sqlc.yaml block, the generate command, and a link into the getting started guide. Drop the same showcase from the documentation landing page, so it lives in one place and that page stays a navigation hub.
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/docs/guide/working-with-json.md (1)
148-149: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winHandle the nullable result before dereferencing
user.
get_useris documented as returningmodels.User | None, but this example accessesuser.preferenceswithout narrowing the optional value. Pyright will report a possibleNonedereference.Suggested fix
user = await get_user(conn, id_=1) +assert user is not None user.preferences.theme.dark_mode # True - typed all the way down🤖 Prompt for 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. In `@docs/content/docs/guide/working-with-json.md` around lines 148 - 149, Update the get_user example to handle the possible None result before accessing user.preferences.theme.dark_mode. Add an explicit null check or other type-narrowing flow, while preserving the demonstrated typed access for an existing user.
🤖 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/content/_index.md`:
- Around line 96-114: Add version: "2" to the sqlc.yaml example before the
plugins configuration so the snippet is a valid v2 configuration while
preserving the existing plugin and SQL settings.
In `@docs/content/docs/getting-started.md`:
- Around line 314-354: Update both the asyncpg and aiosqlite examples to run
inside an async def main() coroutine, add the required asyncio import, and
invoke main with asyncio.run(main()) so await, async for, and async with are not
used at module scope.
- Around line 21-41: Add blank lines between each fenced code block and its
surrounding Hextra tab shortcode lines in the asyncpg, aiosqlite, and sqlite3
tabs, including before each opening fence and after each closing fence, so all
affected examples satisfy MD031.
---
Outside diff comments:
In `@docs/content/docs/guide/working-with-json.md`:
- Around line 148-149: Update the get_user example to handle the possible None
result before accessing user.preferences.theme.dark_mode. Add an explicit null
check or other type-narrowing flow, while preserving the demonstrated typed
access for an existing user.
🪄 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.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1a0b0aa5-8043-4ee6-b017-6eab5d8c9579
📒 Files selected for processing (8)
.changes/unreleased/Added-20260721-140000.yamlREADME.mddocs/content/_index.mddocs/content/docs/_index.mddocs/content/docs/getting-started.mddocs/content/docs/guide/drivers.mddocs/content/docs/guide/model-types.mddocs/content/docs/guide/working-with-json.md
💤 Files with no reviewable changes (1)
- README.md
Follow the feature grid with the things a visitor still has to go looking for: the same table rendered as all four model types, the correctness story behind the generated code, and the setup snippet, ending on a link into the getting started guide. Cards bottom align their text so it can sit under an image, which leaves a gap above short cards once a taller sibling stretches the grid row. Top align text only cards and leave cards with an image alone.
The footer showed the theme's default placeholder. Override the copyright i18n string at site level, matching the LICENSE holder so the two cannot drift.
The async examples used await, async for and async with at module scope, which is a SyntaxError, so anyone copying them got nothing. Run them from an async def main under asyncio.run, in the getting started page and in the drivers, sqlite type conversion and JSON pages that had the same problem. Guard the JSON example against a missing row before reaching into the returned model, since the query returns an optional. Add the required version key to the sqlc.yaml snippet on the home page, which was not a valid v2 configuration without it. Separate fenced blocks from the surrounding tab shortcodes with blank lines, matching how the converter page already wrote them.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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/content/docs/getting-started.md`:
- Around line 346-370: Update the Python example around asyncpg.connect in main
to wrap all query usage in a try/finally block and await conn.close() in the
finally clause, ensuring the connection is closed even when a query or print
operation fails.
In `@docs/content/docs/guide/drivers.md`:
- Around line 30-35: Update the main function’s asyncpg connection flow to wrap
the get_field_naming query in a try/finally block and await conn.close() in the
finally clause, preserving the existing query behavior while ensuring the
connection is always closed.
In `@docs/content/docs/guide/sqlite-type-conversion.md`:
- Around line 20-24: Add an `import sqlite3` statement to the Python snippet in
the `sqlite3` tab before the existing `sqlite3.connect` call, so the example
runs when copied verbatim.
🪄 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.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8d575164-2bac-4eea-916d-64f75dc7fb0a
📒 Files selected for processing (9)
docs/assets/css/custom.cssdocs/content/_index.mddocs/content/docs/getting-started.mddocs/content/docs/guide/docstrings.mddocs/content/docs/guide/drivers.mddocs/content/docs/guide/model-types.mddocs/content/docs/guide/sqlite-type-conversion.mddocs/content/docs/guide/working-with-json.mddocs/i18n/en.yaml
Checking the guide against the generated fixtures turned up several claims that were simply wrong. There is no Querier class. Each query file gets its own class named after the file, taking the connection in the constructor and exposing it again as a conn property, so document that shape instead. The exec family was described loosely: execlastid is int | None and refers to the last affected row, execresult is a status string on asyncpg but a cursor on the sqlite drivers, and execrows reports 0 or -1 depending on the driver when nothing is affected. A one query can also return a generated row class or a bare scalar rather than a model, and a many function is not a coroutine even on the async drivers. Stop claiming every sqlc macro works. sqlc.slice only reaches the type layer: the SLICE placeholder is never expanded, so the query fails once the driver is handed a list. Point people at ANY instead. Redirect the old converters URL, which moved under the guide.
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
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/content/docs/guide/writing-queries.md`:
- Line 172: Update the usage example calling
QueriesFieldNamings(conn).get_field_naming so it awaits the async method and
demonstrates receiving the query result rather than an unexecuted coroutine.
🪄 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.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1f69a3c0-df00-4c98-947e-9338c3729144
📒 Files selected for processing (5)
README.mddocs/content/docs/guide/converters.mddocs/content/docs/guide/writing-queries.mddocs/content/docs/reference/configuration-options.mddocs/content/docs/reference/feature-support.md
sqlc.slice is a supported macro whose placeholder expansion is being fixed before the next release, so list all four macros as supported again rather than calling it unsupported. Leave a short note about the current release behaviour pointing at the tracking issue, to be removed once the fix lands.
The generated method is a coroutine on the async drivers, so calling it without await hands back an unexecuted coroutine rather than the row. Note that sqlite3 methods are plain functions and need no await.
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
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/content/docs/reference/feature-support.md`:
- Around line 11-20: Update the macro support statement in the feature-support
documentation to qualify sqlc.slice as having a known runtime limitation in
v0.5.1 rather than presenting every macro as fully supported. In the
accompanying callout, replace the time-sensitive “fix is landing before the next
release” wording with a neutral statement that the problem is tracked in issue
`#210`, while preserving the PostgreSQL ANY workaround.
🪄 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.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 3e992654-73c1-4474-9f05-6be0ea07ec46
📒 Files selected for processing (4)
docs/content/docs/guide/converters.mddocs/content/docs/guide/writing-queries.mddocs/content/docs/reference/configuration-options.mddocs/content/docs/reference/feature-support.md
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
Builds the documentation site out from a 4-page scaffold into a complete set, and slims the README to match.
Structure follows the two-tier onboarding and uniform page template that makes the hikari-lightbulb v3 docs good: a fast Quickstart, then a paced guide, with canonical lookup tables split out into a reference section. Ordering is encoded with front-matter
weightin steps of ten, leaving room to insert pages later.Every guide page follows the same shape: intro -> specification/contract -> incremental snippets -> complete example -> pitfalls.
Highlights
json/jsonbcolumns withmsgspecstructs: why an override cannot do it, thestrwire-type contract (including themsgspec.json.encodereturnsbytesgotcha), a nested-struct example across models/converters/sqlc.yaml, the generated output, multiple JSON columns with different shapes, nullable/array behaviour, validation semantics, and stdlib-json and pydantic variants.| None) and arrays (collections.abc.Sequence[T]) are layered on.override,converter, andpy_typeobject schemas.Accuracy
All generated-code examples are taken verbatim from the committed test fixtures - models for all four model types, the
:one/:many/:exec/:copyfrombodies, the enum with itsVALUE_24Hsanitization, the override read/write conversions, and all three docstring conventions rendered for the same function. Guide pages show the no-docstring form, sincedocstringsdefaults tonone.While cross-checking against the source, two real options turned out to be missing from the README's table:
indent_charandchars_per_indent_level. Both are now documented in the configuration reference.README
Slimmed from 239 to 105 lines. Keeps the badges, intro, example config, a linked feature list, development/changelog, and credits; the option table and per-feature sections now live on the site (the README's own note said they were there "while they are ported over").
Validation
{{< tab name="..." >}}API -tabs items=is deprecated in Hextra 0.12 and was emitting build warnings.Summary by CodeRabbit