Switch Python API reference to Quarto #640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merged

nrichers merged 72 commits into main from nrichers/sc-4660/python-api-with-quarto

Mar 20, 2025

Collaborator

nrichers commented Jan 30, 2025 •

edited

Loading

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

Before	After

Modified files

site/Makefile — Updated make python-docs to handle the new Quarto docs
site/_quarto.yml — Updated to use the new QMD source and removed the post-render action for Python docs
python-docs.zip (DELETED) — No longer needed with the new Quarto source

Bonus: make clone now 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 generated
site/validmind/_metadata.yml — Configuration for Python API content
site/validmind/_sidebar.yml — Generated sidebar for Python docs
site/validmind/validmind.css — Styling for the API docs
site/validmind/validmind.qmd, site/validmind/validmind/** — Generated API documentation matching the codebase and pdoc structure

Notes 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 preview`

Important: If you test this PR locally, delete the site/_site folder first to remove outdated Python HTML files.

(This step is unnecessary when running quarto render, which removes old HTML output automatically.)

`Makefile`

To test how the Quarto Markdown source files get from the validmind-library repo into this one:

gh pr checkout 640
make clean
make clone BRANCH=nrichers/sc-4660/python-api-with-quarto
make python-docs

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

nrichers added 21 commits

December 4, 2024 14:17


          Remove old python-docs make action & files, rough in new action, and …

a957fdb

…install quartodoc


          Test embed of quartodoc output

9d1721c


          Interim commit to preserve work

3212f37


          Update make python-docs

a0f67b1


          Remove post-render action for python-docs and update validmind packag…

9e47488

…e embeds


          Interim commit to preserve work

082846b


          Interim commit to preserve work

65de392


          Interim commit to preserve work

172eb2e


          Interim commit to preserve work

3945bd9


          Interim commit to preserve work

fbcaf37


          Interim commit to preserve work

a25d541


          Interim commit to preserve work

c8b7cf7


          Update API reference docs

a46bc29


          Rework Makefile, experiment with sidebar fragment

a665702


          Save point

a86b385


          Sidebar experiments


          More sidebar experiments

eb92cae


          More sidebar fixes

d707e80


          Sidebar wildcard experiments

074394f


          Save point

9ff9cbb


          Merge branch 'main' of github.com:validmind/documentation into nrichers/

2eb0c21

sc-4660/python-api-with-quarto

nrichers added DO NOT MERGE internal labels

nrichers changed the title ~~Add Quarto Python Docs — IN PROGRESS~~ [DEMO] Add Quarto Python Docs — IN PROGRESS

nrichers changed the title ~~[DEMO] Add Quarto Python Docs — IN PROGRESS~~ [DEMO] Quarto Python Docs — IN PROGRESS

Contributor

github-actions bot commented Jan 31, 2025

A PR preview is available: Preview URL


          Save point

3f776f0

Contributor

github-actions bot commented Jan 31, 2025

A PR preview is available: Preview URL


          Save point, re-add muted CSS

c06f2e5

Contributor

github-actions bot commented Jan 31, 2025

A PR preview is available: Preview URL

Contributor

github-actions bot commented Mar 5, 2025

A PR preview is available: Preview URL


          Update Quarto source

cc41732

Contributor

github-actions bot commented Mar 5, 2025

A PR preview is available: Preview URL


          Update Quarto source

2a174f0

Contributor

github-actions bot commented Mar 5, 2025

A PR preview is available: Preview URL


          Update Quarto source

bd90727

Contributor

github-actions bot commented Mar 5, 2025

A PR preview is available: Preview URL


          Fix RawData anchor

0bc85b6

validbeck self-requested a review

March 6, 2025 00:39

Contributor

github-actions bot commented Mar 6, 2025

A PR preview is available: Preview URL


          Update Quarto source

ee0f417

Contributor

github-actions bot commented Mar 6, 2025

A PR preview is available: Preview URL


          Fixed broken link

d32ac5a

validbeck requested changes

View reviewed changes

Collaborator

validbeck left a 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.

Contributor

github-actions bot commented Mar 6, 2025

A PR preview is available: Preview URL

nrichers added 2 commits

March 6, 2025 11:02


          Add comment to workaround

801fe81


          Merge branch 'nrichers/sc-4660/python-api-with-quarto' of github.com:…

1d14df9

…validmind/documentation into nrichers/sc-4660/python-api-with-quarto

Contributor

github-actions bot commented Mar 6, 2025

A PR preview is available: Preview URL

validbeck self-requested a review

March 6, 2025 23:36

validbeck approved these changes

View reviewed changes

Collaborator

validbeck left a comment

One last suggestion (my bad for missing it the 1st few rounds) but I think we're ready! 🚀

site/developer/model-testing/testing-overview.qmd Outdated Show resolved Hide resolved


          Update Quarto source

ecc655d

Contributor

github-actions bot commented Mar 7, 2025

A PR preview is available: Preview URL


          Update site/developer/model-testing/testing-overview.qmd

26dc76d

Co-authored-by: Beck <164545837+validbeck@users.noreply.github.com>

Contributor

github-actions bot commented Mar 10, 2025

A PR preview is available: Preview URL

nrichers added 3 commits

March 19, 2025 19:55


          Refresh Quarto API source

560d11f


          Merge branch 'nrichers/sc-4660/python-api-with-quarto' of github.com:…

c9ae934

…validmind/documentation into nrichers/sc-4660/python-api-with-quarto


          Merge branch 'main' into nrichers/sc-4660/python-api-with-quarto

a81f307

Contributor

github-actions bot commented Mar 20, 2025

A PR preview is available: Preview URL

nrichers merged commit f5e5f31 into main

2 of 3 checks passed

nrichers deleted the nrichers/sc-4660/python-api-with-quarto branch

March 20, 2025 03:36

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation highlight