-
-
Notifications
You must be signed in to change notification settings - Fork 188
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.
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
Tutorials infrastructure: switch to sphinx+text-based notebook workflow #36
Conversation
* Add skeleton page from sphinx-quickstart. * Convert source files from ipynb to md: jupytext -k python3 --from notebook --to myst *.ipynb * Add md files to sphinx site. * Change index to mystmd and add binder link.
Provides more options for buttons in theme. Enable download and github interaction buttons. * Add launch button w/ prelim configuration. Configuration will likely need to be adjusted after merge. * Add logos, titles, favicon to theme.
Build sphinx site.
* Remove cloud-service-based workflow (e.g. reviewnb) * Add circleCI artifact redirect badge
Build directly from markdown and take advantage of theme options for enabling downloaded nb's
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Landing page should now look like the README. Also moved gifs to make them accessible both in the repo and the site.
* Handle formatting complaint in style guide. * Turn off execution of cell that raises exception.
Thanks, @rossbar ! I'll give it a try locally and see how that goes. Could the static site be served through github pages? I can do the README update with new gifs. |
That would be my preference!
Great :) I didn't intend for the TODO's to be blockers or anything, just a running list of ideas that I had while putting this together, so no pressure! |
I tried this locally and this looks really good. Now for the plan:
Thank you so much, @rossbar ! I think this is an improvement over ReviewNB which, unfortunately, doesn't look ready to use. |
I agree - I'll set up the CI/CD to deploy to github pages on merge (similar to numpy devdocs). Down the road, I think we can still use github pages to host but redirect somewhere else (e.g. somewhere on numpy.org) pretty easily if that's what the community decides to do.
I expect there will be plenty to tweak as we try this out. Fortunately the set of tools is pretty flexible so I think we can accommodate a lot of different approaches. I'll update the CI config this week for deployment. LMK if anything else crops up that needs attention! |
The numpy devdocs is a bit strange in that there is a dedicated repo just for the rendered docs. Another option, and one that projects seem to be adpoting more, is to have a dummy branch inside the repo, like
For a sample github-action based workflow that pushes built documents to a branch in the current repo see here This example has a few other things on the
We did have a bit of a problem getting it going, since the PR tries to do If you are concerned about the size of the repo, you can do destructive commits to |
Maybe split the PRs: only build in this PR and then in another one deploy? |
I agree with @mattip . As far as I'm concerned, this is good for merging. But it would be useful to have the opinion of others more experienced in CI and this kind of workflow. |
Someone with admin permissions and a circleci account needs to add the needed integrations to get this to work |
@mattip What needs to be done? |
I think I have the necessary permissions for the CircleCI. I also have to disable the CircleCI on my own fork for it to take effect. I'm happy to do so after merging. |
Hello folks! Finally merging this - thanks @rossbar and all who contributed to the discussions. This may mean that our README is outdated for a while, so I'll add a note there explaining we're still figuring this out. Edit: I'll also organize the remaining todo items into issues so we can keep track of what's left to do. |
This is a follow-up to numpy#36
This is a follow-up to numpygh-36.
Overview
Changes the workflow for the
numpy-tutorials
repo to use a text-based format for Jupyter notebooks and sphinx+myst for running & testing the notebooks, and generating a static tutorials site.The text-based notebook format expresses notebooks in markdown rather than the typical json format associated with
.ipynb
files. This enables a workflow for submission and review that maps onto the standard GitHub reviewing workflow.Authors can still submit content in
.ipynb
format - it will be converted to.md
for review using jupytext. Both html and downloadable notebooks (.ipynb) are generated as part of the build process. CircleCI has been configured to handle this on GitHub. A standard sphinx workflow can be used to run/evaluate changes locally (though users are not required to use the sphinx for authoring/reviewing!)The sphinx-book-theme is based on the
pydata-sphinx-theme
used in the main NumPy docs, and provides convenient buttons both for launching notebooks on cloud services (e.g. binder & jupyterhub) as well as downloading notebooks to run locally.Todo
site/index.md
, which is the landing page for the sphinx site (see faa5368)content/*.md
and remove any leftover cruft (e.g. colab metadata) (see 9915375).ipynb
and.md
formatsPost merge
numpy/numpy-tutorials
and deactivate it rossbar's fork