Include gallery images in CircleCI-generated docs

[charlesbmi]

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/examplesscripts.

Unfortunately, our current PR/CircleCI docs do not include figures, showing them only as broken links, e.g.:

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 at http://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 or build_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:

• https://github.com/squidfunk/mkdocs-material/blob/950d1e41fb540a29fd785d00e73a1c5ae5e0a2f1/docs/plugins/offline.md?plain=1#L37-L39
• https://www.mkdocs.org/user-guide/configuration/#use_directory_urls It seems there is some slight incompatibility between the offline and mkdocs-gallery plugins in terms of where files/images are expected.

Changes

• Swap out mkdocs's offline plugin for a custom plugin on CircleCI builds
  • Note: the offline plugin is already disabled on local builds and when building the production website.
  • The custom plugin simply sets each page's url to its dest_uri. Some examples of original url and dest_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 mode

  • It unfortunately wasn't as simple as disabling the offline mode, because CircleCI simply uploads the web-page files to an S3 bucket (rather than serving a mkdocs website), so CircleCI won't take care of redirecting url='contributing/' to url='contributing/index.html'

• Decided it is more important to:

  • be able to view the gallery-generated images, than to:
  • be able to site-search the docs offline. We can still site-search the docs online and on CircleCI

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.

[codecov-commenter]

Codecov Report

All modified lines are covered by tests :white_check_mark:

:loudspeaker: Thoughts on this report? Let us know!.

[charlesbmi]

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.

[charlesbmi]

Thanks @NewtonSander ! Merging.