[DOC] Auto-generate openapi.json

conda-incubator / conda-store

Data science environments, for collaboration. ✨

https://conda.store

BSD 3-Clause "New" or "Revised" License

137 stars 44 forks source link

[DOC] Auto-generate openapi.json #782

Open pavithraes opened 3 months ago

pavithraes commented 3 months ago

Ref: #766

Description

This pull request:

Adds a script and action to auto-update the openapi.json static file. This file is used to generate the REST API docs.
Adds conda-store.sqlite to .gitignore

Pull request checklist

[ ] Did you test this change locally?
[ ] Did you update the documentation (if required)?
[ ] Did you add/update relevant tests for this change (if required)?

Additional information

While this works, there is likely a cleaner/minimal way to do this. Please let me know if you ideas to simplify this!
Please make sure to squash-merge this PR.

How to test

I've tested it on my fork: https://github.com/pavithraes/conda-store/pull/4

netlify[bot] commented 3 months ago

Deploy Preview for kaleidoscopic-dango-0cf31d ready!

Name	Link
Latest commit	269d2ccdc066d581bd708522b51b7ab4bb5af2d7
Latest deploy log	https://app.netlify.com/sites/kaleidoscopic-dango-0cf31d/deploys/65f34d4bf9e3b40008cb07ff
Deploy Preview	https://deploy-preview-782--kaleidoscopic-dango-0cf31d.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify[bot] commented 3 months ago

Deploy Preview for conda-store canceled.

Name	Link
Latest commit	dc4a875253a781a79440785dee7eae69f796b1e0
Latest deploy log	https://app.netlify.com/sites/conda-store/deploys/6668518359d6e100084d7fba

pavithraes commented 1 month ago

Thanks for the review!

Quick question: this will make a PR against the branch that someone is trying to merge, right?

@peytondmurray No, this workflow opens a PR against main when a conda-store release is made. Since the docs are deployed separately, this helps us keep the API ref up-to-date with each released version.

peytondmurray commented 4 weeks ago

@peytondmurray No, this workflow opens a PR against main when a conda-store release is made. Since the docs are deployed separately, this helps us keep the API ref up-to-date with each released version.

So my one problem with this is that doc versions that track the main branch will have API docs that are out of date. Are we publishing docs for the main branch? Do we even need to worry about this?

pavithraes commented 3 weeks ago

That's fair. The docs are currently only built against main.

I didn't want to generate the file on every merge to main because not all PRs affect the API.

I think we can re-generate this on updates to certain files. I'm not sure which specific files to track here, but I can update the PR to regenerate openapi.json on updates to anything within conda_store_server/ for now.