docs: expand and restructure Ontos documentation site - #680
Open
danielrozo-db wants to merge 9 commits into
Open
docs: expand and restructure Ontos documentation site#680danielrozo-db wants to merge 9 commits into
danielrozo-db wants to merge 9 commits into
Conversation
Replace demo_project/install_local pages with install_demo and install_marketplace, add configs admin guide, refresh user-guide pages with screenshots, and update landing page styling. Co-authored-by: Isaac
Combine projects.md and teams.md into projects_teams.md, remove the redundant admin_guide/teams.md, add related screenshots, and update domains.md. Co-authored-by: Isaac
Flesh out the data contracts user-guide page with the ODCS v3.1.0 lifecycle stages, contract creation/upload steps (including a sample Customer 360 ODCS payload), and the certify/publish/request/version actions. Point the projects and teams page at core concepts instead of repeating the definitions. Co-authored-by: Isaac
Replace the placeholder dev_guide/api_reference.md stub with a dev_guide/api/ section documenting the FastAPI backend routes, generated from the route definitions. - add dev_guide/api/index.md covering the interactive OpenAPI surfaces (/docs, /redoc, /openapi.json) and API base URL - add per-resource reference pages: data_contracts, data_products, data_domains, projects, teams, tags, costs - add dev_guide/api/_category_.json so the section is labelled "API Reference" and links to its index - remove the placeholder api_reference.md and custom_migrations.md stubs, which held only heading scaffolding - drop both stubs from the docs exclude list in docusaurus.config.ts now that the pages they hid are gone Verified with `npm run build` — no broken links or anchors under onBrokenLinks/onBrokenAnchors: 'throw'. Co-authored-by: Isaac
The per-resource API pages mixed naming styles: some front-matter
titles were plural ("data products", "costs"), some carried an "API"
suffix ("Projects API", "Teams API"), and a few H1 headings were
lowercase where the sidebar label was title-cased.
- use a singular lowercase `title` on every page, so the sidebar
labels read consistently: cost, data contract, data domain,
data product, project, tag, team
- drop the redundant "API" suffix from the projects, tags, and teams
titles — the section is already labelled "API Reference"
- title-case and singularize the H1 headings to match
- remove trailing whitespace after the data domain and data product
headings
Verified with `npm run build` — no broken links or anchors.
Co-authored-by: Isaac
Replace the getting-started placeholder stubs with real setup instructions and give the section its own landing page, so the Marketplace and Databricks Labs paths are documented end to end. Getting started: - add getting_started/index.md as the section landing page, covering the two deployment paths and the shared workspace prerequisites (foundational model API, DBSQL endpoint, admin entitlement, UC managed volume) - point getting_started/_category_.json at that page instead of a generated index, and rename the label to "Getting started" - write up the Marketplace install walkthrough, from the Marketplace listing through app resources, usage policies, and the app URL - document loading and deleting the bundled demo data via the demo-data POST and DELETE endpoints, with a warning against running it on a production instance - trim install_databricks.md: hoist the prerequisites to the landing page and link to dev_guide/lakebase_setup.md for instance creation rather than repeating the steps - reorder the pages so Marketplace comes before Databricks Labs - add the 10 screenshots these walkthroughs reference Fixes surfaced by the section link change: - retarget the homepage "Getting Started" button from the removed /docs/category/getting-started generated index to /docs/getting_started - add .md extensions to the landing page's sibling links so they resolve from the section root Also: - use a deployment-URL placeholder in the API reference example commands instead of localhost:8000 - exclude the admin_guide jobs_workflows, previews, and roles stubs from the sidebar until they have content - switch the projects/teams multi-team note from :::info to :::tip - drop a stray trailing "//" from faq.md Verified with `npm run build` — no broken links or anchors under onBrokenLinks/onBrokenAnchors: 'throw'. Co-authored-by: Isaac
|
|
mvkonchits-db
previously approved these changes
Aug 7, 2026
mvkonchits-db
left a comment
mvkonchits-db
left a comment
Contributor
There was a problem hiding this comment.
Reviewed — docs-only, clean improvement to the Docusaurus site. The per-resource API split and consolidated install flow are a clear step up. Approving.
Two small nits to fix before merge (in introduction/concepts.md, they render on the public page):
- L23: "There are tow types of projects" → "two"
- L23: "Teams provide logical isolation … and allows multiple teams" → "allow"
- L42: "They are witten in a SQL-like … DSL" → "written"
One architectural observation (not blocking this PR): this expands the public site docs while the Ask Ontos copilot has its own grounding corpus under docs/handbook/. The two now describe an overlapping conceptual core (e.g. introduction/concepts.md vs handbook/entities-glossary.md, plus lifecycle/role material) with no shared source, so definitions will drift over time.
Worth a follow-up to make the handbook the canonical source for the shared conceptual layer (glossary, lifecycle states, role model) and have the website import/wrap those definitions rather than re-authoring them — install guides, API reference, and screenshots stay website-specific; "under the hood" internals stay handbook-specific. Flow must be handbook → website, since the {#anchor} conventions and clean section bodies are load-bearing for the search_ontos_handbook retriever. Not for this PR; just flagging so we don't entrench the divergence.
- concepts.md: correct "tow" -> "two", "witten" -> "written", and "allows" -> "allow" for subject-verb agreement - add contract_lifecycle.png to docs assets Co-authored-by: Isaac
mvkonchits-db
enabled auto-merge
August 13, 2026 08:26
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
3 participants
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
Documentation-only improvements to the Ontos Docusaurus site (
website/ontos/). This expands and restructures the getting-started, user-guide, admin-guide, and API reference docs, adds a landing page, and includes supporting screenshots.Changes
Getting started
index.mdoverview.install_demo.mdandinstall_marketplace.md; updatedinstall_databricks.md.demo_project.mdandinstall_local.mdin favor of the consolidated flow.User guide
data_contracts.md— documents the data contract lifecycle, versions, and actions.projects.mdandteams.mdinto a singleprojects_teams.mdpage.data_products.mdanddomains.md.Admin guide
configs.mdpage; trimmedteams.md; minor fix injobs_workflows.md.API reference
api_reference.mdinto per-resource pages underdev_guide/api/:costs,data_contracts,data_products,data_domains,projects,tags,teams, plus anindex.mdand category config.Site / landing page
src/pages/index.tsx,index.module.css,custom.css,docusaurus.config.ts).Assets
Notes
This pull request and its description were written by Isaac.