search

jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
196 stars 29 forks source link

caching (locally) npm pkgs' dist at docs build stage #150

Closed 2bndy5 closed 1 year ago

2bndy5 commented 2 years ago

~This may be off topic, but I figured I'd mention it now that this aims to solve #111.~ I think the fetching of mermaid.js should be added to external_resource_cache. Currently, the sphinx_immaterial.mermaid_diagrams ext is on by default because the theme src seems to be fetching the mermaid.js resource regardless.

Agreed, and also for MathJax. But that could be deferred for a separate PR.

Originally posted by @jbms in https://github.com/jbms/sphinx-immaterial/issues/144#issuecomment-1218796196

2bndy5 commented 1 year ago

About mermaid.js

I found this upstream comment that explains how the mermaid.js lib is used in the theme's JS bundle.

Note
This following ideas imply that the mermaid ext in our theme becomes optional instead of always enabled.

So, I can add the mermaid.js lib to this theme's external resources ext (on build-init if the mermaid ext is enabled), but I'm not sure this fits into the consolidated bundle because the bundled JS is written to load the script from a separate file (only when there are <div class="mermaid"> elements present). https://github.com/jbms/sphinx-immaterial/blob/f04bc71a5a205dff7884146caf9d3a0e53462d36/src/assets/javascripts/components/content/code/mermaid/index.ts#L72 What I think I need to do is somehow read the contents of the mermaid.min.js dist and create a <script> element with the contents as children -- this would be extra bloat if not using mermaid. I'm not sure if there is a TS function in the inherited codebase to do that because the watchScript() function is only designed to create <script src="path/to/min.js"></script> elements.

Alternatively, I can just add the mermaid.js dist from cache to built docs' _static folder and simply change the path specified in the watchScript() arg. In this scenario, we would have to exclude the mermaid.min.js contents from the bundled JS though.

I have yet to look into how we could exclude the theme's mermaid-related JS code from the bundle. It definitely won't be needed when the mermaid ext is not enabled. This bit seems like a separate issue because there is other JS code that could be conditionally be excluded (eg not using all available html_theme_options["features"]).

About mathjax

This should be much easier since the upstream implementation is basically just telling the user to add the mathjax lib themselves. Sphinx already ships with mathjax support, so we may just need to document how the user can build docs that self-host the mathjax dist.

TBH, I'm not really sure there's anything in the inherited codebase that is specific to mathjax (aside from some CSS). So, I don't think mathjax support in our external resources ext is needed, rather it may be better managed by the doc project's author(s).