Overture docs V2 update - #48
Open
MitchellShiell wants to merge 28 commits into
Open
Conversation
✅ Deploy Preview for overturedocs canceled.
|
Resolves PR #911's conflict against origin/develop. 18 develop commits absorbed; the single two-sided edit, the support link in docs/02-Reference/00-submitting-metadata.md, keeps this branch's rewrite over develop's stale docs.overture.bio path. Develop's own additions are intact: the -ad allow-duplicates flag, the JetBrains README logo, and the repo-wide formatter pass.
Resolves PR #504's conflict against origin/develop. 6 develop commits absorbed across four conflicts: two support/reference-link rewrites kept over develop's stale docs.overture.bio paths, README.md combined with develop's Environment typo fix, and the Makefile Compose detection kept as this branch's probe-with-fallback in place of develop's hardcoded $(shell which docker) compose. Develop's score -> score-client image rename, --remove-orphans, and JetBrains logo are all intact. The branch's removal of --validate from the upload options table still holds: #503 adds no CLI flag, and --validate is declared only on DownloadCommand.
PR #257 was BEHIND by one commit (8195c9a, next@^12 vulnerability upgrade). Rebased onto origin/main rather than taking GitHub's offered merge commit, for consistency with the song and score rebases and to keep history linear. No conflicts: that commit touches only package.json and package-lock.json, while the branch touches docs/ and dev-services/.
Resolves PR #448's conflict against origin/main. 43 main commits absorbed, one conflict: README.md, where main and this branch had independently repointed the same stale under-development/lectern link. Main used the older docs/core-software scheme, so this branch's /develop/Lectern/overview wins, matching the site rename already applied across song and score. Main's prettier reformat of docs/03-dictionaryReference.md and its displayName additions survive untouched. The docs/04-viewer/ pages were verified against the rebased packages/ui: entry points, DictionaryTableProps, CustomColumnConfig and MetaValueRenderer all match.
PR #297 targets M5-revised, the TypeScript rewrite, not master. 83 commits absorbed from a 2023 merge base. The Java maestro-app config and the five old doc pages stay deleted; the replacement pages cover their content and are more accurate, since M5-revised's tech.md and README still list the kafka and repository packages that 2cad87c consolidated away, and its setup.md points at a nonexistent .env.schema. Two corrections on top of the rebase: the README still carried master's Java 11 and Maven prerequisites, which would have regressed the TypeScript branch, and both setup guides documented a make help target that does not exist.
Resolves PR #1089's conflicts. 11 commits absorbed, four conflicts. MCP tool names: main's #1088 renamed them to snake_case and this branch still had kebab-case, so main wins, verified against apps/mcp-server/src. docs/mcp-server.md combined, keeping main's new query_arranger Prompts block from #1087 alongside this branch's heading promotion. The two .dev conflicts follow the branch's own drop-.dev-changes intent, so .dev matches main exactly, except tech-debt.md where both entries are kept: they are additive, and this branch's OpenSearch entry explains why its Makefile change removes the start-os target.
Closes the unclosed code fence in docs/03-dictionaryReference.md that trapped the ## Field Restrictions heading inside a code block. Docusaurus was failing the site build on two broken anchors pointing at it, one from the Lectern page itself and one from website/docs/use-docs/administration/01-building-dictionaries.mdx.
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.
Overture docs site v2: restructure into Develop / Deploy / Use / Community
Rebuilds the documentation site around four audience-facing sections, replaces the old
docs/guides/workshopsplit, adds the deployment and AI-assisted data discovery guides, and ships three interactive in-page tools. Component reference docs are pulled in from thesubmodules/doc branches, so this PR is blocked onthe submodule PRs in the table below.
overtureDocsUpdate->main· 16 commits · 185 files (+13,787 / -10,069) plus 7 submodule pin bumps.Submodule merges are preferable before merging docs
Every component's reference docs live in its own repo and are vendored here as a submodule. This PR's pins currently point at branch tips that are not yet on their default branches. Each row must be merged first, then the pin re-pointed at the resulting default-branch commit before this PR can go in.
submodules/lecternoverture-stack/lecternovertureDocsUpdatemain01fb704submodules/lyricoverture-stack/lyricovertureDocsUpdatemain181bbb1submodules/songoverture-stack/songovertureDocsUpdatedevelop28a01d6asubmodules/scoreoverture-stack/scoreovertureDocsUpdatedevelop38386151submodules/maestrooverture-stack/maestroovertureDocsUpdatemastercbb2bd6submodules/arrangeroverture-stack/arrangerovertureDocsUpdatemainb521460dsubmodules/stageoverture-stack/stageovertureDocsUpdatemain580d785All seven branches are pushed and have no unpushed or uncommitted work.
What changed in this repo
Information architecture
The site moves from
docs/guides/workshop/communityto four audience-oriented Docusaurus plugin instances, each with its own sidebar:/developwebsite/docs/develop-docsdevelopSidebars.ts/deploywebsite/docs/deploy-docsdeploySidebars.ts/usewebsite/docs/use-docsuseSidebars.ts/communitywebsite/docs/community-docscommunitySidebars.tssidebars.ts,guidesSidebars.ts,workshopSidebars.tsandcasestudiesSidebars.tsare removed. Navbar becomes Develop / Deploy / Use.
New content
/deploy/deployment): per-component walkthroughs: Keycloak, Song, Score, Lectern, Lyric, search engine, Maestro, Arranger, Stage, plus file transfer, search portal, tabular data submission, and the Arranger MCP server./use/ai-assisted-data-discovery): testing environment, connecting a host, configuration templates, use cases, and deploying your own MCP server./use/administration): building dictionaries, building Song schemas, customizing the data portal, index mappings./develop/api-reference): per-component Swagger pages for Song, Score, Maestro, Lyric, Lectern and Arranger.lecternAPI.jsonadded; the Song, Score, Maestro and Lyric specs are regenerated against current code./use/workshopwith a new generalized intro page.Interactive components
Three browser-only tools, each with a docs page under
/use/config-generators-and-playgrounds:Build and dependencies
3.9.2to3.10.2; package renamedbridge-poctooverture-docs.@overture-stack/lectern-dictionary,@overture-stack/lectern-ui, the CodeMirror editor stack, and@docusaurus/plugin-client-redirects.website/docsPlugin.tsgains webpack config to make the Lectern viewer bundle for the browser: aliasesd3-dagto its ESM build (its CJS build pulls in Node built-ins), stubs Node core modules, rewritesnode:-scheme imports, and silences the resultingd3-dagcritical-dependency warning.react/react-dompinned viaoverridesfor@overture-stack/lectern-ui.Merge order
Verification
npm ci && npm run buildinwebsite/is clean