search

mozilla / sphinx-js

Autodoc-style extraction into Sphinx for your JS project
https://pypi.python.org/pypi/sphinx-js/
MIT License
278 stars 80 forks source link

Lazy-load JS in auto* directives #23

Open xmo-odoo opened 7 years ago

xmo-odoo commented 7 years ago

This would be a further enhancement for #21 I guess: currently sphinx-js hooks on builder-inited to parse the JS, but that means it runs jsdoc on the source tree on every build period. This doesn't really matter as it also rebuilds the entire documentation every time.

However if #21 is implemented for large documentations (where the APIdoc "dump" is only a page or two of a much larger whole) many rebuilds will parse the JS source despite not necessarily touching the corresponding pages. At this point it would probably be a good idea for the auto* directives to run JSDoc themselves (possibly in JsRenderer since it's the single entry point for rendering? that would avoid implementing it thrice), thus rebuilds which don't touch either JS sources or rST documents containing auto* directives will not trigger a complete reparsing of the JS source.

erikrose commented 7 years ago

You still propose having jsdoc run over the whole project when it does run, correct? You're just saying "don't run it at all if we never hit a JS directive"?

xmo-odoo commented 7 years ago

Yeah, while it may be possible to do partial runs it would be much much more difficult. Doing collection the first time you hit a directive's run is pretty easy and should not impact the total runtime (much or at all), but it's a pretty serious quality of life improvement when editing docs unrelated to the JS with a significant amount of JS code.