search

spatialaudio / nbsphinx

:ledger: Sphinx source parser for Jupyter notebooks
https://nbsphinx.readthedocs.io/
MIT License
451 stars 130 forks source link

Documenting nbsphinx_assume_equations #603

Closed diego-plan9 closed 2 years ago

diego-plan9 commented 2 years ago

Would it be possible to add nbsphinx_assume_equations to the documentation? I found the (useful!) option recently a bit by chance - when trying to look it up for more details using the 0.8.7 documentation, I could only find a reference in the changelog.

The changelog entry was still enough, though (and looking at the related PR and an issue mentioning the option clarified its usage even more) - it's mostly for making it slightly easier to find.

mgeier commented 2 years ago

Sure, it would be good to add this to the documentation! Do you want to make a PR?

diego-plan9 commented 2 years ago

Thanks for the quick reply! Yes, I can give it a try :+1:

mgeier commented 2 years ago

Just out of curiosity: would you mind sharing in which kind of situation you were using nbsphinx_assume_equations?

diego-plan9 commented 2 years ago

Sure! It was in the context of Debian packaging - nbsphinx 0.8.7 was updated recently in the Debian repositories (previous version was 0.8.0). When I was refreshing another package that relies on nbsphinx for building its documentation, the build process emitted a new warning due to an mathjax being <source>d in the rendered HTML pages from the CDN (which is an issue from the packaging perspective, as it is preferred that the documentation is self-contained, including the js dependencies).

In order to fix the new warning, I was looking for a way to disable mathjax being included in the rendered .html files - that's how I ended up finding the flag. For the record, in the end I went with using mathjax_path and pointing to the local libjs-mathjax copy: but nevertheless, I thought documenting it a bit more would help other users eventually.