feat: version-pinned documentation orchestrator (per-repo aggregation) - #54
Draft
sstruzik wants to merge 4 commits into
Draft
feat: version-pinned documentation orchestrator (per-repo aggregation)#54sstruzik wants to merge 4 commits into
sstruzik wants to merge 4 commits into
Conversation
…repo aggregation) GenerateDocs no longer holds documentation content. Each component owns and builds its own Sphinx docs; this repo pins versions and assembles them: - modules.json: pinned manifest (repo, ref, docs_source, publish path, site_base_url). - orchestrate.py: builds each component from its repo (--clone at ref, or --use-local), two-pass so cross-component intersphinx resolves, then rewrites cross-links to page-relative so the assembled site is relocatable (works under file://). - src/: slimmed to a landing (component cards + home + use cases); drained ~45 duplicated sections/, plus schema/, releases/, redoc/, update-redoc.py (now owned by the components). - build.sh: thin wrapper (./build.sh clone+build; ./build.sh --local). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite README for the orchestrator: local build (--local from sibling checkouts, or orchestrate.py directly), pinned clone (CI), flags, and how to view the static site. Update requirements to the union of every component's Sphinx extensions (add myst-nb, myst-parser, sphinx-design, sphinx-copybutton, oasislmf; drop py3.12-incompatible monolith leftovers) so a fresh-venv build can build all components. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brand the landing with the Oasis logo and palette (matching oasislmf.github.io), and rewrite the per-page 'Oasis documentation home' link (and cross-links) to page-relative so the assembled site is relocatable and the home link works from any component/page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A fresh build venv pulled setuptools>=81, which dropped pkg_resources and broke sphinxcontrib.redoc (OasisPlatform docs). Pin setuptools<81 so the redoc extension imports. Also make the three `here`_ FAQ links anonymous to clear duplicate-target warnings on the landing under Sphinx 7.4. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
2 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.
GenerateDocs no longer holds content. Each component owns/builds its own Sphinx docs; this repo pins versions (
modules.json) and assembles them (orchestrate.py): two-pass build so cross-component intersphinx resolves, then rewrites cross-links to page-relative (relocatable, works under file://). Slimmedsrc/to a landing; drained ~45 duplicatedsections/+schema//releases//redoc/.Part of the cross-repo Oasis documentation restructure (Option B).
Replace the monolithic docs build with a version-pinned orchestrator that aggregates each repo's own documentation.