sphinx-doc/sphinx

Allow `singlehtml` to embed all assets into a single html file

Open

#10,688 opened on 2022年7月21日

GitHub で見る
 (7 comments) (24 reactions) (0 assignees)Python (1,985 forks)batch import
builder:htmlhelp wantedtype:enhancement

Repository metrics

Stars
 (5,625 stars)
PR merge metrics
 (平均マージ 10d 11h) (30d で 11 merged PRs)

説明

Context

The singlehtml builder is a way to combine all pages of the HTML documentation into a single HTML file. This is really useful if you want to quickly share your documentation with other people in a way that they can quickly open in their computer.

However, one challenge is that singlehtml builds also tend to come with a lot of external assets in the local filesystem. For example, CSS files, JS files, etc are packaged alongside the single HTML file. This makes the benefits of "a single HTML file" less powerful, because now you have a collection of files that you need to ship together. It is much more difficult to, for example, attach them to emails and such.

Suggestion

Make it possible (or document how if it is already possible) to make singlehtml builds also include the asset content inside of the HTML file, so that it is a single, self-contained file that can be easily sent to somebody else, and can open anywhere without any external files (at least, local ones).

References

Some folks have also requested this in the Jupyter Book project here:

コントリビューターガイド