Draft
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
b30f5c3 to
b53f07f
Compare
b53f07f to
c384344
Compare
3ecb0d7 to
9a851b3
Compare
9a851b3 to
4aa79e3
Compare
ddf0686 to
2322f60
Compare
ad1679b to
d936cb3
Compare
2322f60 to
eeaed5c
Compare
d936cb3 to
2e27cc7
Compare
eeaed5c to
9b48035
Compare
2e27cc7 to
5aee96b
Compare
9b48035 to
dddff97
Compare
5aee96b to
9bd7af0
Compare
This change restructures the docs build to remove the dependency on the schema repository, enabling faster builds and simpler deployment. Key changes: - Add injectable schema references for dynamic content - Reorganize example files and schema definitions - Optimize image assets (convert large GIFs to MP4s, compress PNGs) - Add staging deployment workflow - Update linting and formatting configurations - Fix package-lock.json for cross-platform compatibility
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.
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:
