Repository navigation
DOC: Migrate Quarto docs from separate repo into main tree - #294
Merged
Merged
Conversation
Copied from materialsgenomefoundation/espei.org at 5e01975. The Git LFS tracked .npy MCMC arrays are replaced by float32 compressed .npz files with one copy per unique dataset.
Drop the Read the Docs configuration and the Sphinx dev dependencies in favor of quartodoc and jupyter, which are needed to build the docs/ site. The API reference is generated by quartodoc at build time, so the release checklist no longer regenerates it by hand.
CHANGES.md is the single source for release notes. It was converted with pandoc, with issue roles rewritten as GitHub issue links and the unreleased section dropped. The docs include the file directly.
A pre-render script writes _variables.yml from importlib.metadata so the sidebar title and any page can reference the version. Links to the docs source now point at the ESPEI repository.
The hand-maintained copy of the API reference tree in _quarto.yml is
replaced by quartodoc's sidebar generation. The full site sidebar is
declared under quartodoc.sidebar with the {{ contents }} placeholder for
the API pages, and the generated _sidebar.yml is loaded through
metadata-files.
The Docs workflow renders the site on every push and pull request and deploys it to the gh-pages branch: releases under their tag and the master branch under dev/. switcher.json at the site root lists the deployed versions and a small script injected into every page adds a version selector to the sidebar and a banner on non-latest versions. The Sphinx build job is removed from the test workflow.
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.
A few years ago I set up https://github.com/materialsgenomefoundation/espei.org as a test of Quarto docs. I liked it, so kept it. It's been stale and I've been concerned about docs drift (I forgot to update for 0.9.1). Besides being experimental, the other reason I made it was to be able to store full NumPy traces and lnprob files in git-lfs, which would be too large and cumbersome for direct storage. This saves those as float32 and as
.npzto save on space and remove that concern.This PR
uv), ii) changelog, iii) versioning