search

mozilla / sphinx-js

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

feat: Cache JSDoc results #115

Closed ptbrowne closed 5 years ago

ptbrowne commented 5 years ago

I am working on a documentation site pulling several repositories.

JSDoc data extraction can take 30s. I thought it could help performance to save the result to a file configured in app.config.

EDIT: Build is red, I am looking into it. I welcome any feedback on this PR, I may have pushed the PR a bit early but I did not want it to be lost. Thanks for sphinxjs.

ptbrowne commented 5 years ago

I haven't had time to work again on this PR, sorry for the delay.

erikrose commented 5 years ago

My only big concern is this: how do you ensure the cache file is removed when stale? You may have a nice build process that ensures that happens when the JS code changes, but I doubt most potential sphinx-js users do. And it would probably be nontrivial—though possible—to have sphinx-js itself handle that.

ptbrowne commented 5 years ago

I understand you concern, I had the same worry, but then I thought that since it is opt-in, users wanting to use this would only use this knowing that they should remove the cache manually if thinking it is stale (by rming it).

erikrose commented 5 years ago

Ah, I missed that it was opt-in. Of course it is. Part of this PR should be adding docs saying as much (and explaining how to use it, including an admonition to clean up your stale caches) to the readme under Configuration Reference.

erikrose commented 5 years ago

When you come back to this, you might want to merge in from master. We just switched test runners, which might make your debugging easier.

erikrose commented 5 years ago

Merged! Thanks for the patch! If you want to be sure it doesn't accidentally break later, you should also write up some tests that exercise it. Thanks again!