search

QuantEcon / sphinxcontrib-jupyter

A Sphinx Extension for Generating Jupyter Notebooks
BSD 3-Clause "New" or "Revised" License
77 stars 23 forks source link

Treatment of Static Assets #308

Open mmcky opened 4 years ago

mmcky commented 4 years ago

The treatment of static assets needs a rework as it has real limitations at the moment. In the current re-write of the extension I propose we adopt a new approach to asset management.

Sphinx make html: [Information Only]

The current sphinx html writer produces a _static folder with a collection of assets contained in a single folder. This isn't convenient for all notebook cases as it is difficult to find supportive static assets for individual notebooks. It works well for large websites.

notebooks: [sphinxcontrib-jupyter]

rather than implement different ways the static assets are collected for ipynb, jupyter-html etc. I propose we adopt a file/asset approach to the static folder. If an rst file document.rst contains a figure picture.png then the file would be copied to _static/document/picture.png. This allows a unique path without worrying about file collisions between documents. It also helps locate static assets for notebooks.

For slide and course notebook cases we can modify this to include the document folder in the directory the notebook is written so it would be easy to distribute the notebook and files.

mmcky commented 4 years ago

in the future we can also investigate using notebook attachment for a fully unified distribution experience.