Closed charlesbmi closed 11 months ago
All modified lines are covered by tests :white_check_mark:
:loudspeaker: Thoughts on this report? Let us know!.
Per discussion with @d-lucena, I have moved the plugin owner to https://github.com/agencyenterprise/mkdocs-offline-links-plugin; I have updated the pyproject.toml dependencies here.
Thanks @NewtonSander ! Merging.
https://github.com/agencyenterprise/neurotechdevkit/issues/141
Introduction
We use CircleCI to generate docs webpages for every pull request. This is particularly helpful to view for pull requests that add or edit
docs/examples
scripts.Unfortunately, our current PR/CircleCI docs do not include figures, showing them only as broken links, e.g.:![image](https://github.com/agencyenterprise/neurotechdevkit/assets/3221512/280939e5-7f03-4d62-8ff0-7e815f73509e)
The root cause appears to be an issue with the paths, as a local build (which shows images correctly) puts, e.g. the
plot_time_reverse
page athttp://127.0.0.1:8000/neurotechdevkit/generated/gallery/plot_time_reverse/
but then on CI, it shows up not in its own folder but as:https://output.circle-artifacts.com/output/job/a9676679-2d73-455d-a473-c666c02fa461/artifacts/0/html/generated/gallery/plot_time_reverse.html
This appears to be the result of a slight difference in
build_docs_pr
vs local doc builds orbuild_docs_no_cache
for the main website. Specifically, the PR build_docs use https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/ , which changes whether pages are directory URLs or.html
files:offline
andmkdocs-gallery
plugins in terms of where files/images are expected.Changes
mkdocs
's offline plugin for a custom plugin on CircleCI buildsoffline
plugin is already disabled on local builds and when building the production website.url
to itsdest_uri
. Some examples of originalurl
anddest_uri
values:File(src_uri='index.md', dest_uri='index.html', name='index', url='./')
File(src_uri='contributing.md', dest_uri='contributing/index.html', name='contributing', url='contributing/')
Design decisions
Explicitly change the page URLs in
offlink-links
modeoffline
mode, becauseCircleCI
simply uploads the web-page files to an S3 bucket (rather than serving amkdocs
website), soCircleCI
won't take care of redirectingurl='contributing/'
tourl='contributing/index.html'
Decided it is more important to:
Behavior
View figure images in the generated CI docs, e.g. (from https://output.circle-artifacts.com/output/job/8e437392-4580-4896-9d68-8d87b5fbcb4d/artifacts/0/html/generated/gallery/plot_customized_center_frequency/index.html)
Not solved
https://output.circle-artifacts.com/output/job/8e437392-4580-4896-9d68-8d87b5fbcb4d/artifacts/0/html/generated/gallery/index.html still links the examples using the directory naming, e.g. https://output.circle-artifacts.com/output/job/8e437392-4580-4896-9d68-8d87b5fbcb4d/artifacts/0/html/generated/gallery/plot_customized_center_frequency . We need to add
/index.html
to these links to make them work.