Switch Python API reference to Quarto#640
Switch Python API reference to Quarto#640nrichers merged 72 commits intomainvalidmind/documentation:mainfrom nrichers/sc-4660/python-api-with-quartovalidmind/documentation:nrichers/sc-4660/python-api-with-quartoCopy head branch name to clipboard
Conversation
…install quartodoc
sc-4660/python-api-with-quarto
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
|
A PR preview is available: Preview URL |
validbeck
left a comment
There was a problem hiding this comment.
Since we did have to go with the zero-width whitespace as a workaround, can we please leave a comment on the variable file for future reference? 🙏🏻 (I would do it, but I think I'm still not understanding the root cause of the issue as I wasn't the one that investigated it...)
Otherwise, there was a broken link when we changed the .html to .qmd that I fixed — we linked to the full docs site URL instead of the relative root /validmind folder so that was expected.
|
A PR preview is available: Preview URL |
…validmind/documentation into nrichers/sc-4660/python-api-with-quarto
|
A PR preview is available: Preview URL |
validbeck
left a comment
There was a problem hiding this comment.
One last suggestion (my bad for missing it the 1st few rounds) but I think we're ready! 🚀
|
A PR preview is available: Preview URL |
Co-authored-by: Beck <164545837+validbeck@users.noreply.github.com>
|
A PR preview is available: Preview URL |
…validmind/documentation into nrichers/sc-4660/python-api-with-quarto
|
A PR preview is available: Preview URL |
Internal notes for reviewers
This PR replaces the pdoc-generated Python HTML docs with Quarto Markdown source, which is rendered alongside the rest of the site: Live preview
Relates to: validmind/validmind-library#306
Modified files
site/Makefile— Updatedmake python-docsto handle the new Quarto docssite/_quarto.yml— Updated to use the new QMD source and removed the post-render action for Python docspython-docs.zip(DELETED) — No longer needed with the new Quarto sourceBonus:
make clonenow accepts a branch for PR testing.New files and folders
Do not review here, post comments to [#306]( validmind/validmind-library#306:
site/validmind/README.md— How the Quarto Markdown gets generatedsite/validmind/_metadata.yml— Configuration for Python API contentsite/validmind/_sidebar.yml— Generated sidebar for Python docssite/validmind/validmind.css— Styling for the API docssite/validmind/validmind.qmd,site/validmind/validmind/**— Generated API documentation matching the codebase and pdoc structureNotes on reviewing
site/validmind/Do not review the Quarto Markdown files here. If you see issues, review them in the PR that generates them: validmind/validmind-library#306
The Quarto Markdown files are a drop-in replacements with only minor differences.
quarto previewImportant: If you test this PR locally, delete the
site/_site folderfirst to remove outdated Python HTML files.(This step is unnecessary when running
quarto render, which removes old HTML output automatically.)MakefileTo test how the Quarto Markdown source files get from the
validmind-libraryrepo into this one:You should see the
site/validmind/folder disappearing and reappearing with the new source files.External release notes
This release introduces a completely redesigned Python API reference using Quarto instead of the previous HTML-generated docs. The new ValidMind Library documentation features improved navigation with a familiar sidebar, enhanced code signature styling, and integration with our main docs site search.
The documentation structure mirrors the Python package layout, ensuring backward compatibility with our old Python API reference while providing a more maintainable and reader-friendly experience.
ValidMind Library