docs: Add docs generation to schema build command #284
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughThis change refactors the documentation for various code host connections and configuration files by replacing large, inline JSON schema blocks with imported schema components. It introduces new JSON Schema files for each connection type (GitHub, GitLab, Gitea, Gerrit, Bitbucket) and for search contexts, storing them in dedicated snippet files. The documentation now imports and renders these schema components instead of embedding raw JSON. Additionally, the schema generation tooling is updated to output schema files to both source and documentation directories, and the main Sourcebot configuration schema references these external definitions. TypeScript interfaces and JSON schema files are also added for search contexts. Changes
Sequence Diagram(s)sequenceDiagram
participant Docs as Documentation (.mdx)
participant Snippet as Schema Component (.mdx)
participant Schema as JSON Schema File
Docs->>Snippet: Import schema component (e.g., <GitHubSchema />)
Snippet->>Schema: Render schema from external JSON schema file
Docs->>User: Display rendered schema in documentation
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (26)
✨ Finishing Touches
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
brendan-kellam
changed the title
![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
🧹 Nitpick comments (38)
docs/snippets/schemas/v3/shared.schema.mdx (1)
1-1: Grammar: fix header comment
The header reads "THIS IS A AUTO-GENERATED FILE." For grammatical correctness, consider changing it to "THIS IS AN AUTO-GENERATED FILE."docs/snippets/schemas/v3/bitbucket.schema.mdx (3)
1-1: Grammar: fix header comment
As with other snippets, update "THIS IS A AUTO-GENERATED FILE." to "THIS IS AN AUTO-GENERATED FILE."
16-51: Token definition duplication
Thetokenproperty redefines the same structure fromshared.schema.mdx. Consider referencing the sharedTokendefinition via$refto avoid schema duplication and keep the snippets DRY.
54-60: Use standard JSON Schema URI format
The property uses"format": "url"with a custom regex. Draft-07 specifies"format": "uri". You may simplify by switching to:- "format": "url", - "pattern": "^https?://[^\\s/$.?#].[^\\s]*$" + "format": "uri"This leverages built-in URI validation and removes the need for a custom pattern.
docs/docs/connections/bitbucket-data-center.mdx (1)
8-8: Add missing semicolon to MDX import.
For consistency with the existing imports, terminate theimport BitbucketSchemastatement with a semicolon:-import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx' +import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx';docs/self-hosting/more/declarative-config.mdx (1)
6-6: Add missing semicolon to MDX import.
Please add a semicolon at the end of the import for consistency:-import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx' +import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx';docs/docs/connections/bitbucket-cloud.mdx (1)
8-8: Add missing semicolon to MDX import.
Align this import with the surrounding statements by adding a semicolon:-import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx' +import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx';docs/docs/connections/gerrit.mdx (1)
65-65: Remove placeholder JSX comment.The comment
{/* asdf */}appears to be a placeholder that should be removed before merging.-{/* asdf */}docs/snippets/schemas/v3/gerrit.schema.mdx (1)
1-1: Nit: Grammar in auto-generated file header
The comment reads "THIS IS A AUTO-GENERATED FILE". Consider updating to "THIS IS AN AUTO-GENERATED FILE" in your codegen template for grammatical correctness.packages/schemas/src/v3/searchContext.schema.ts (1)
1-1: Nit: Grammar in auto-generated file header
The comment reads "THIS IS A AUTO-GENERATED FILE". Consider updating to "THIS IS AN AUTO-GENERATED FILE" in your codegen template.docs/snippets/schemas/v3/gitea.schema.mdx (1)
12-47: Add example forenvtoken variant
Thetokenschema only shows an example for thesecretvariant. Consider adding an example for theenvvariant, e.g.:{ "env": "GITEA_TOKEN_ENV_VAR" }This will improve clarity for users choosing the environment-variable approach.
docs/snippets/schemas/v3/gitlab.schema.mdx (6)
6-11: Consistent capitalization for title
The title is"GitlabConnectionConfig", but the official product name is "GitLab". Consider updating to"GitLabConnectionConfig"for consistency across schemas.
12-47: Enhancetokenexamples by includingenvvariant
Thetokenschema correctly supports bothsecretandenvobject formats, but theexamplesarray only shows thesecretcase. Adding an example for theenvvariant (e.g.,{"env": "GITLAB_TOKEN"}) would better illustrate usage.
59-63: Clarifyallproperty behavior
Sinceurldefaults to"https://gitlab.com/", thealloption will be ignored by default. Consider revising either the default value forurlor the description ofallto avoid surprising users who expect it to work out-of-the-box.
64-115: Add default values for array properties
Properties such asusers,groups,projects, andtopicscurrently have no"default". To document the fallback behavior and align with other schemas, add"default": []to these array properties.
116-157: Provide defaults forexclude.topics
Inside theexcludeobject,projectshas"default": []buttopicsdoes not. Adding"default": []toexclude.topicswill ensure consistent behavior when the field is omitted.
158-198: Consider default forrevisions
Therevisionsobject governs indexing of branches and tags. Defining a"default": {}would clarify what happens when no explicit revisions are provided.docs/snippets/schemas/v3/github.schema.mdx (3)
6-11: Use proper product capitalization
The title is"GithubConnectionConfig", but the official product name is "GitHub". Consider updating to"GitHubConnectionConfig"for consistency.
12-19: Includeenvexample for token
Theexamplesarray undertokenonly demonstrates thesecretvariant. To fully illustrate the schema’s capabilities, add an example for theenvvariant, e.g.:{"env": "GITHUB_TOKEN"}
48-57: Verify URL pattern strictness
The current regex forurlallows most valid URLs but may permit some edge cases. Consider tightening the pattern or documenting its limitations to prevent unexpected host strings.docs/snippets/schemas/v1/index.schema.mdx (3)
4-8: Add top-leveltitleordescription
This schema defines repository mirroring configs but lacks a"title"or"description"at the root. Including one (e.g.,"title": "ZoektMirrorConfig") would enhance clarity in generated docs.
29-37: Addtitleto connection definitions
Insidedefinitions.GitHubConfiganddefinitions.GitLabConfig, consider adding a"title"(and optional"description") to improve schema introspection and generated documentation.
121-129: Enforce non-emptyConfigsarray
If at least one mirror config is required, add"minItems": 1to theConfigsarray to prevent empty configurations.docs/snippets/schemas/v2/index.schema.mdx (1)
9-24: EnhanceTokendefinition with secret reference
TheTokenschema supports a literal string or an object with"env". To align with v3 and facilitate secret management, consider adding a variant:{ "type": "object", "properties": { "secret": { "type": "string", "description": "Name of the secret containing the token." } }, "required": ["secret"], "additionalProperties": false }docs/snippets/schemas/v3/index.schema.mdx (3)
12-67: Adddefaultvalues toSettingsproperties
Unlike v2, these settings lack"default"keywords. Adding defaults (e.g.,2097152formaxFileSize,3600000forreindexIntervalMs, etc.) will ensure consistent auto-population in tooling.
12-67: Useintegertype for discrete values
All settings representing bytes or time intervals are typed as"number". Switching to"integer"would better reflect their discrete nature and align with other schemas.
70-110: Remove redundant$schemainsideSearchContext
Embedding a full$schemadeclaration in theSearchContextdefinition is unnecessary in this snippet. Removing it will reduce clutter and potential confusion.docs/snippets/schemas/v3/connection.schema.mdx (11)
1-2: Use an HTML comment and correct the article in the auto-generated notice.
MDX supports HTML comments natively; switching improves readability. Also, grammatically use “an auto-generated”:- {/* THIS IS A AUTO-GENERATED FILE. DO NOT MODIFY MANUALLY! */} + <!-- THIS IS AN AUTO-GENERATED FILE. DO NOT MODIFY MANUALLY! -->
3-6: Add a unique$idfor better schema references.
Defining an$idin the root makes it easier to reference programmatically and avoids brittle fragment pointers:{ "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://sourcebot.dev/docs/snippets/schemas/v3/connection.schema.json", "title": "ConnectionConfig", "oneOf": [
7-218: Remove redundant$schemadeclarations in subschemas.
The"$schema"keyword only applies at the document root; nested occurrences are ignored and clutter the file:- { - "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "title": "GithubConnectionConfig", ... },
16-50: Extracttokeninto a sharedTokendefinition.
Inlinedtokenschemas and JSON pointers tooneOf[0]are brittle. Define aTokeninshared.schema.mdxand reference it instead:- "token": { - "description": "A Personal Access Token (PAT).", - "anyOf": [ ... ] - }, + "token": { + "$ref": "shared.schema.mdx#/definitions/Token" + },
61-62: Prefer built-in URIformatover custom regex.
Draft-07 supports"format": "uri", which is clearer and more maintainable than a hand-rolled pattern:- "url": { - "type": "string", - "format": "url", - "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" + "url": { + "type": "string", + "format": "uri"
220-356: Avoid JSON pointers to array indices for reuse.
Referencing#/oneOf/0/properties/tokenties the schema to its current ordering. Use shared definitions instead:- "token": { - "$ref": "#/oneOf/0/properties/token", + "token": { + "$ref": "shared.schema.mdx#/definitions/Token", ... }
292-305: Add a default for GitLabtopicsto align with GitHub.
Specifying"default": []makes clear that absence equates to “no filter”:"topics": { "type": "array", "items": { "type": "string" }, "minItems": 1, + "default": [], "description": "List of project topics ..." },
357-451: Standardize default for Giteaexclude.repos.
Unlike GitHub, Gitea’sexclude.reposlacks a default. Adding"default": []ensures consistent behavior:"repos": { "type": "array", "items": { "type": "string" }, + "default": [], "description": "List of individual repositories to exclude..." },
443-445: Reuse sharedGitRevisionsinstead of an array-index pointer.
Referencing the GitHub revisions schema by index is fragile. Use a direct$reftoshared.schema.mdx#/definitions/GitRevisions:- "revisions": { - "$ref": "#/oneOf/0/properties/revisions" - } + "revisions": { + "$ref": "shared.schema.mdx#/definitions/GitRevisions" + }
452-508: Consider default empty arrays for Gerritprojects.
Adding"default": []to optional lists likeprojectsandexclude.projectsimproves self-documentation:"projects": { "type": "array", + "default": [], "items": { "type": "string" }, ... },
509-620: Add defaults for Bitbucket filter arrays.
Properties such asworkspaces,projects, andreposshould default to[]so absence clearly means “no filter”:"workspaces": { "type": "array", + "default": [], "items": { "type": "string" }, ... }, "projects": { "type": "array", + "default": [], "items": { "type": "string" }, ... }, "repos": { "type": "array", + "default": [], "items": { "type": "string" }, ... },
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (25)
docs/docs/connections/bitbucket-cloud.mdx(2 hunks)docs/docs/connections/bitbucket-data-center.mdx(2 hunks)docs/docs/connections/gerrit.mdx(2 hunks)docs/docs/connections/gitea.mdx(2 hunks)docs/docs/connections/github.mdx(2 hunks)docs/docs/connections/gitlab.mdx(2 hunks)docs/self-hosting/more/declarative-config.mdx(2 hunks)docs/self-hosting/more/search-contexts.mdx(2 hunks)docs/snippets/schemas/v1/index.schema.mdx(1 hunks)docs/snippets/schemas/v2/index.schema.mdx(1 hunks)docs/snippets/schemas/v3/bitbucket.schema.mdx(1 hunks)docs/snippets/schemas/v3/connection.schema.mdx(1 hunks)docs/snippets/schemas/v3/gerrit.schema.mdx(1 hunks)docs/snippets/schemas/v3/gitea.schema.mdx(1 hunks)docs/snippets/schemas/v3/github.schema.mdx(1 hunks)docs/snippets/schemas/v3/gitlab.schema.mdx(1 hunks)docs/snippets/schemas/v3/index.schema.mdx(1 hunks)docs/snippets/schemas/v3/searchContext.schema.mdx(1 hunks)docs/snippets/schemas/v3/shared.schema.mdx(1 hunks)packages/schemas/src/v3/index.schema.ts(1 hunks)packages/schemas/src/v3/searchContext.schema.ts(1 hunks)packages/schemas/src/v3/searchContext.type.ts(1 hunks)packages/schemas/tools/generate.ts(1 hunks)schemas/v3/index.json(1 hunks)schemas/v3/searchContext.json(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: build
🔇 Additional comments (27)
docs/snippets/schemas/v3/shared.schema.mdx (2)
5-6: Schema declaration and root type are correct
The$schemareference and"type": "object"declaration align with draft-07 JSON Schema.
7-35: Token definition looks solid
TheanyOfstructure correctly enforces eithersecretorenv, andadditionalProperties: falseprevents extra fields.docs/docs/connections/gitlab.mdx (2)
6-6: Importing GitLab schema snippet
The import path aligns with other MDX docs and will pull in the shared snippet correctly.
182-182: Rendering the<GitLabSchema />component
Replacing the inline JSON block with the component ensures consistency and reusability.docs/docs/connections/gitea.mdx (2)
6-6: Importing Gitea schema snippet
The snippet import matches the established pattern for MDX-based schema components.
148-148: Rendering the<GiteaSchema />component
Delegating schema display to the imported component improves maintainability.docs/docs/connections/github.mdx (2)
6-6: Importing GitHub schema snippet
The import path is correct and mirrors the other connection docs.
177-177: Rendering the<GitHubSchema />component
Embedding the<GitHubSchema />component replaces the old inline block as intended.packages/schemas/src/v3/index.schema.ts (1)
69-73: ApproveSearchContextschema enrichment.
Adding the explicit"$schema"and"title"properties to theSearchContextdefinition increases clarity and aligns with JSON Schema Draft-07 conventions.docs/docs/connections/bitbucket-data-center.mdx (1)
81-81: Schema snippet insertion is correct.
Replacing the raw JSON reference with<BitbucketSchema />improves maintainability and ensures documentation stays in sync with the schema definition.docs/self-hosting/more/declarative-config.mdx (1)
39-39: Modular schema snippet integration looks good.
The<ConfigSchema />component cleanly replaces the inline JSON block and keeps the documentation aligned with the source schema.schemas/v3/index.json (1)
69-70: Reference externalsearchContext.json.
By replacing the inlineSearchContextdefinition with a$refto./searchContext.json, the schema is now modular and reusable across code and docs.docs/docs/connections/bitbucket-cloud.mdx (1)
102-102: Schema snippet rendering is correct.
Embedding<BitbucketSchema />in the reference accordion streamlines the documentation and ensures consistency.docs/docs/connections/gerrit.mdx (1)
6-7: LGTM! Good modularization of schema documentation.The import and usage of the
GerritSchemacomponent from a reusable snippet improves maintainability by centralizing schema definitions.Also applies to: 70-70
docs/self-hosting/more/search-contexts.mdx (1)
6-7: LGTM! Well-structured schema reference implementation.The import and usage of
SearchContextSchemacomponent is implemented correctly, including the helpful link to the raw schema file. This modular approach will make it easier to keep documentation and schemas in sync.Also applies to: 113-117
packages/schemas/tools/generate.ts (1)
8-8: LGTM! Excellent refactoring to support dual output formats.The updated generate script now correctly outputs schemas to both source files and documentation snippets with appropriate formatting for each. This supports the PR objective of keeping documentation and schemas automatically synchronized.
Key improvements:
- Separate paths for source and documentation outputs
- Proper MDX formatting for documentation snippets
- Consistent banner comments in both outputs
- Directory creation with recursive option for nested paths
Also applies to: 13-14, 21-26, 30-46, 50-50, 57-57
schemas/v3/searchContext.json (1)
1-42: LGTM! Well-structured schema with clear documentation.The SearchContext schema is well-defined with:
- Clear property descriptions explaining expected formats
- Helpful examples demonstrating proper usage
- Appropriate required field designation
- Prevention of additional properties to maintain schema integrity
This schema will provide good documentation and validation for search context configurations.
docs/snippets/schemas/v3/gerrit.schema.mdx (1)
3-59: Schema structure looks valid
TheGerritConnectionConfigJSON schema correctly defines the object shape, required properties, strict typing, pattern validation, and examples.packages/schemas/src/v3/searchContext.schema.ts (1)
2-44: Valid JSON Schema definition
ThesearchContextSchemacorrectly defines the JSON Schema with the requiredincludeproperty, clear descriptions, examples, andadditionalProperties: false. Usingas constensures precise TypeScript typings.packages/schemas/src/v3/searchContext.type.ts (1)
6-19: Interface matches schema definition
TheSearchContextinterface accurately mirrors the JSON Schema's required and optional properties, with comprehensive JSDoc comments for each field.docs/snippets/schemas/v3/searchContext.schema.mdx (1)
2-44: Valid JSON Schema snippet for SearchContext
This MDX file correctly defines theSearchContextschema: requiredinclude, optionalexcludeanddescription, examples are provided, andadditionalPropertiesis set tofalse.docs/snippets/schemas/v3/gitea.schema.mdx (1)
3-162: Schema structure looks correct
TheGiteaConnectionConfigschema accurately defines all properties—includingtype,token,url, sync filters, andrevisions—along with proper patterns, defaults, and strict validation.docs/snippets/schemas/v3/gitlab.schema.mdx (1)
1-2: Auto-generated file notice is clear
The header clearly indicates this file is auto-generated and should not be modified manually.docs/snippets/schemas/v3/github.schema.mdx (1)
1-2: Auto-generated file notice is clear
The header properly marks this as an auto-generated file. No manual edits are required.docs/snippets/schemas/v1/index.schema.mdx (2)
1-2: Auto-generated file notice is clear
The header correctly indicates this file is auto-generated and should not be manually edited.
83-84: Verify required fields inGitLabConfig
Currently only"Type"is required forGitLabConfig. Evaluate whether properties likeGitLabURLorCredentialPathshould also be mandatory to avoid incomplete configurations.I can assist by searching existing v1 config examples if needed.
docs/snippets/schemas/v3/connection.schema.mdx (1)
621-623: The closing braces and code fence correctly terminate the JSON block; no further action required.
brendan-kellam
force-pushed
the
bkellam/schema-docs-sync
branch
from
80e7409 to
bb03c97
Compare
1 participant
This PR modifies
packages/schemas/tools/generate.tsto write the resolved schema to a mdx, which can be used as a reusable snippet in Mintlify. This makes it s.t., our docs & schemas will always be in sync.Summary by CodeRabbit