Closed melissawm closed 5 months ago
I don't see the ipython notebook example int he built html docs. I had expected to see it appear as a page in the examples gallery. @melissawm is this part working for you?
EDIT: Ah, I see now. Any jupyter notebook files are being deliberately skipped (see setup
function in docs/conf.py
)
def setup(app):
"""Set up docs build.
* Ignores .ipynb files to prevent sphinx from complaining about multiple
files found for document when generating the gallery
* Rewrites github anchors to be comparable
* Adds google calendar api key to meetings schedule page
"""
app.registry.source_suffix.pop(".ipynb", None)
I thought we wanted the notebooks to be executed and included? https://github.com/napari/napari-animation/issues/70
I see that there is a single line of text in the gallery.rst page linking to it, but that is easy to overlook. It also leaves us vulnerable to the code in that notebook going out of date, and we won't know it produces errors.
Summarizing the current status (Melissa, please add or correct anything I've got wrong here)
Items remaining for this PR:
linkcheck_ignore
and rewrite_github_anchor
functions staying or going (see discussion thread here). Done, they can be removed. It doesn't even look like the main napari/docs repo is actually running a link checker anyway, and we don't have one here yet either.Nice to have, possibly in a later PR:
Set up Github secret key for docs deployment (apparently I don't have the right permissions for this - @jni who does?)
I don't think you actually need this to deploy to the same-repo's gh-pages. See the deploy to github pages docs (though they are not as clear as I'd like about this):
Alternatively you can set the following in your workflow file to grant the action the permissions it needs.
permissions: contents: write
To answer your Q, the napari steering council can do that if needed. But I think it's not. 😅
Ok, maybe something is funky about how the napari/docs repository handles this, that's where the secret key business came from. If someone would like to edit the new deploy_docs.yml
file here to remove that requirement, that would be fantastic.
Yeah the issue with the napari/docs repo is that it needs to deploy to a different repo. Is that the case here or are we just deploying to the gh-pages branch?
@jni is right, this can be simplified. Unfortunately I won't have time this week to work on this PR but I can take a look next week if it's still pending. Thanks for the fixes @GenevieveBuckley !
I've made some progress towards getting the deployment working.
docs/_build
, docs/_static
, and docs/gallery
)index.html
file. Because we bundle multiple directories into the artifact, I think github pages might not know where to find our main page _build/index.html
. ./
Switching to actions/upload-pages-artifact helped fix the issue.
ls -lR /path/to/folder | grep '^l'
as suggested by the top stackoverflow answer here. I didn't find anything, but I'm also not sure if this was the right way to check or not.I've uploaded the most recent artifact and the CI logs here on google drive. You can open the html website locally in your browser and see that it all looks correct and the gallery videos play.
If anyone can help figure out why the artifact is causing problems, that would be wonderful.
Note: I'm using actions/upload-artifact instead of the suggested actions/upload-pages-artifact, mostly because I was finding it tricky to include multiple directories (we need our build, static, and gallery files). I don't think that could be causing the problem, but should mention it.
Finally, I've made a copy of the repo (not a fork, it won't deploy github pages on a fork) to play with things here: https://github.com/GenevieveBuckley/napari-animation-copy/ I can add people to this repo if you like.
I've got it working now - you can see a working test website here: https://genevievebuckley.github.io/napari-animation-copy/gallery.html EDIT: I've deleted the test website now the main website here is working https://napari.org/napari-animation/gallery.html
In the end it was simplest to add a command in the Makefile to copy the video files across into docs/_build/gallery/images, then point the actions/upload-pages-artifact to just the docs/_build folder (which now contains everything we need).
It works! 🎉 🚀 https://napari.org/napari-animation/gallery.html
Awesome! 🎉
Supersedes #173
May close #80
I haven't really looked at the scrapers, because currently the docs execute even if the images are not in the gallery. Feel free to push to this PR if you know how to build the animation scraper. I can also try to come up with a solution later.
cc @GenevieveBuckley