Notebooks in the docs with nbsphinx
Closed this issue · 11 comments
Hello PyZX people!
Just dropping by to let you know I've just added a back-and-forth interface between DisCoPy and PyZX.
Also, I've started using nbsphinx for including jupyter notebooks into readthedocs. It works so well that you can even interact with PyZX diagrams (drag and drop nodes) directly inside the docs: https://discopy.readthedocs.io/en/main/notebooks/new-features-0.3.3.html
That would surely be a great feature for PyZX's documentation. Let me know if you want some help in setting it up.
Cheers,
Alexis
Hey Alexis, thanks for the heads-up! Having Jupyter notebooks directly in the documentation looks like a great idea!
@akissinger This might also be a nice thing to let someone implement for the qhackathon
Is there any objection to moving the demos/ directory under the doc/ directory? The notebooks to be processed by nbsphinx need to be under doc/. Right now, there's a rule to copy the notebooks in demos/ to under _static, but the nbsphinx processing happens before the copying of the custom static files.
Well for one, changing the folder will break many existing links in papers that use the demos. It might have been better to put them in doc, but we didn't think that far ahead.
But for some notebooks that are explicitly meant as demonstrations of functionality, and not of results of papers that should be fine.
Looking at the files in demos/, it looks like they can be divided into two types: those associated with papers ("results" notebooks), and those which document or demonstrate the software ("tutorial" notebooks). The question is whether this division is a clean one, i.e., whether any papers link to the "tutorial" notebooks. If not, then we can simply move the "tutorial" notebooks under say doc/notebooks/ for nbsphinx.
The sphinx conf.py has a html_static_path rule to copy the contents of demos/ into _static, but unfortunately "static" means just that: the files there won't be processed. What was the intention of this rule? I don't see where these notebooks which have been copied are being used internally. Are these the links referred to in the papers (and thus need to be preserved because they've been used externally)?
I've set up the basic nbsphinx config in PR #152 and moved the gettingstarted.ipynb file under doc/notebooks/, to show that it works. If you rebuild the HTML, you'll get a notebook where you can interact with the PyZX diagrams, which is pretty nice.
Another thing to consider is that while the notebooks work nicely in HTML mode, the parts which are based on javascript won't work in the PDF output. I guess code would have to be added to turn the interactive diagrams into static images when outputting to PDF.
If it is possible to detect when the notebook is being processed into a PDF, then you can change the setting so that zx.draw() uses matplotlib instead of D3.
I don't remember what the reasoning was behind including demos into static. Does it break anything if this rule is removed?
I don't remember what the reasoning was behind including demos into static. Does it break anything if this rule is removed?
It was added in this commit, with the purpose apparently being to link to the gettingstarted.ipynb file copied into _static. But subsequently the link was changed to the version on github. In any case, PR #152 will make nbsphinx process this notebook, so the rule to copy it (the copying of all the other notebooks seems only to be a side effect) will not be necessary.
If it is possible to detect when the notebook is being processed into a PDF, then you can change the setting so that zx.draw() uses matplotlib instead of D3.
According to this comment, this isn't possible by design, but there's a way to work around it by setting an environment variable. I've added this logic to PR #152. (I've tested it locally but I can't test if this will work in readthedoc's environment.)