An easy way to specify a list of assets that should be copied over.

Is your feature request related to a problem? Please describe.

My teaching notebooks often include links to local assets (images, data or code files, …). I would want these assets to be accessible from the HTML version as well.

Describe the solution you’d like

I would like to have a simple way to specify a list of files (or file globs) that sphinx should copy over to _build/html, preserving the nested structure (i.e. foo/bar.py should be copied over as _built/html/foo/bar.py). This could be some MANIFEST style file, or some config option.

Describe alternatives you’ve considered

Sphinx’s html_extra_path is inconvenient as it flattens the directory structure. I.e. if foo/bar.py is specified, then the copy will land in _build/html/bar.py.

The workaround I found is to create an assets directory, and reproduce the directory structure there, with links to the original files, and add the following to _config.yml

sphinx:
  config:
    html_extra_path: ['assets']

The first step is cumbersome at best.

Bonus

Make it so that the assets would be also available to code executed in the thebelab cells. This one is tough as the kernel is running on a remote Jupyter server, and thus does not have direct access to the files locally hosted on the web server.

[chrisjsewell]

For option 2, I think the caption part is not yet implemented in Myst-Parser

Yes it is 😄 See the big jupyter-book documentation refresh that is nearly finished in #911 (and will be released as v0.8.0) https://deploy-preview-911--jupyter-book.netlify.app/content/figures.html#markdown-figures

[nthiery]

@nthiery what’s the way in which you’d imagine referencing them? E.g. all of those things seem like things you’d want people to download, but the {download} role will trigger an asset copy if I recall correctly

Ah, ok, good to know. Pending confirmation, let’s try and see if, in practice, the download role + new myst features for images cover all the use cases. Worst comes to worst, a work around could be to use a dummy myst page listing all the desired assets with download links.