New reference documentation from Pydantic#222
Open
Jennings Anderson (jenningsanderson) wants to merge 13 commits intomainfrom
Open
New reference documentation from Pydantic#222Jennings Anderson (jenningsanderson) wants to merge 13 commits intomainfrom
Jennings Anderson (jenningsanderson) wants to merge 13 commits intomainfrom
Conversation
e6ea8d0 to
abd354e
Compare
b6bf09d to
fa2e953
Compare
fa2e953 to
0b290b7
Compare
0b290b7 to
fe96c27
Compare
e957a48 to
5cdf6c4
Compare
056ef89 to
097bf05
Compare
2862cbe to
d39b96b
Compare
090537e to
c4df84e
Compare
dada7c1 to
780b023
Compare
9bd7af0 to
506a387
Compare
Generated from overture-schema-codegen (code-generation branch)
using explicit theme selection to exclude internal types:
overture-codegen generate \
--theme addresses --theme base --theme buildings \
--theme divisions --theme places --theme transportation \
--format markdown --output-dir docs/schema/reference
Cross-theme types (names, perspectives, cartography, scoping,
strings, sources, primitives, geometry) now live under
types/{subsystem}/ instead of flat at reference root or under
Names/.
Transportation segments (road, rail, water) and their ~50
referenced types are not yet generated -- the codegen doesn't
decompose the Segment discriminated union into individual
models. A WIP banner on the schema index notes this gap.
Broken link warnings enabled in docusaurus.config.js to
surface pre-existing and new issues during builds.
The codegen now outputs a flatter directory structure: types/ split into core/ (names, cartography, scoping, sources, perspectives) and system/ (primitives, string types, ref types). Theme feature-type subdirectories removed (e.g. addresses/address/address.md becomes addresses/address.md). Internal cross-reference links updated to match; no content changes. sidebars.js rewritten to match the new layout.
Fixes newlines that break tables.
Include Segment, a union type with complex rendering requirements
Fix sidebar
Include model-level validation rules
🚀 Overture Maps docs branch preview deployed!You can review your changes at https://staging.overturemaps.org/docs/pr/222/index.html ♻️ Last refreshed: 2026-02-25T00:27:49Z |
Collaborator
Author
Jennings Anderson (jenningsanderson)
left a comment
There was a problem hiding this comment.
🚀
Include various minor improvements
27232c9 to
9b563cf
Compare
Super-linter summary
Super-linter detected linting errors For more information, see the GitHub Actions workflow run Powered by Super-linter MARKDOWNNATURAL_LANGUAGE |
Super-linter summary
Super-linter detected linting errors For more information, see the GitHub Actions workflow run Powered by Super-linter MARKDOWNNATURAL_LANGUAGE |
Super-linter summary
Super-linter detected linting errors For more information, see the GitHub Actions workflow run Powered by Super-linter MARKDOWNNATURAL_LANGUAGE |
Super-linter summary
Super-linter detected linting errors For more information, see the GitHub Actions workflow run Powered by Super-linter MARKDOWNNATURAL_LANGUAGE |
Super-linter summary
Super-linter detected linting errors For more information, see the GitHub Actions workflow run Powered by Super-linter MARKDOWNNATURAL_LANGUAGE |
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
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.
Moving to Pydantic!
This PR updates and simplifies the docs to show easier, table-based schema docs.
Enhancements to
docscode:/schema/reference Updates:
Today, everything available under docs.overturemaps.org/schema lives here: https://github.com/OvertureMaps/schema/tree/dev/docs/schema. When docusaurus builds the docs, it fetches the .mdx, schema, and examples from the schema repo. This is a lot of moving parts and kind of ugly.
This PR removes that requirement in favor of simple, machine-readable markdown files that can be self-generated by the schema and used by documentation.
See https://staging.overturemaps.org/docs/pr/222/schema/reference/address/ for an example of how we envision these reference docs rendering.
Next Steps:
Before this is ready to merge, we need to develop the ability for the schema to create self-describing documentation with examples as markdown files, example:
The full schema should be a series of markdown files nested by theme/type that have relative links. We can adjust the
SmartTablecomponent as necessary to make the links work — but the markdown should be a nice, standalone set of files.If the examples that were embedded were actually derived from the examples in the schema repository after being validated by the schema itself, that would be best case scenario.
Once this ability exists, we can update this repository to fetch these markdown files (or checkout schema and build the markdown as part of the publish). The idea is these files can be dropped directly into
docs/schemato power this part of the documentation.Docs Preview
Example:
