A third thing you can do with jupyter-sphinx is enable thebelab. This connects the sphinx page to a binder instance and you can run the code and change it, which sympy-live already does too. SymPy live integration was really ahead of its time!
Jason moorepants.info +01 530-601-9791 On Tue, Jul 7, 2020 at 1:05 PM Aaron Meurer <[email protected]> wrote: > On Tue, Jul 7, 2020 at 1:29 PM Jason Moore <[email protected]> wrote: > > > > There are some ways to integrate Jupyter notebooks with Sphinx that > didn't exist when we created the sympy-notebooks repo. One main issue is > that you only want to commit un-executed notebooks to the main SymPy repo > so that the binary outputs don't pollute and grow the git repo. > > > > Some options: > > > > - Commit unexecuted notebooks to a repo and then have a CI service run > nbconvert to convert them to HTML pages. This is what we did here: > https://www.sympy.org/scipy-2017-codegen-tutorial/ > > > > - jupyter-sphinx: write rst files with code blocks that are labeled as > jupyter cells. When our CI service builds the docs, these "notebooks" are > run and the output added to the documentation. > https://github.com/jupyter/jupyter-sphinx. I used this for PyDy and I > like the result. It can even preserve some ipywiget-like functionality. > Here is an example from PyDy: > https://pydy.readthedocs.io/en/latest/examples/multidof-holonomic.html > (note the 3D viz at the end). I like this because you can write the > documentation in a text editor like normal instead of having to write in > the Jupyter interface. You get a "download as notebook" button also. > > The ability to download the document as an executable notebook is > nice. The other advantage is that you get LaTeX output in the cells, > because it executes like a notebook rather than a Python session. > > Aside from those two things though, I don't see much of a difference > from just writing an RST document in the docs with doctested examples > interleaved with descriptive text. > > Aaron Meurer > > > > > - sphinxcontrib-jupyter: process jupyter notebooks that then get added > to the sphinx docs. You have to write in the Jupyter interface for this one. > > > > There are other options too. I think it would be nice to have the > notebooks integrated within docs. > > > > Jason > > moorepants.info > > +01 530-601-9791 > > > > > > On Tue, Jul 7, 2020 at 11:16 AM Nikhil Maan <[email protected]> > wrote: > >> > >> Hi John, > >> > >> Thanks for showing interest in improving SymPy's documentation. Can you > tell us a little about what kind of tutorials/guides your project would be > focused on? > >> > >> As for incorporating the notebooks, there was a previous discussion at > https://groups.google.com/forum/#!topic/sympy/_5RcJXGOgP4 > >> The plan is to move all the notebooks to the > https://github.com/sympy/sympy-notebooks repository so that all the > notebooks can be at a single standard place. So, I think it will be a good > idea to have any notebooks you create as a part of the project at the same > repo. > >> > >> Also, just to make sure, the deadline for the application is in 2 days, > on July 9, 2020, 18:00 UTC > >> > >> Regards, > >> Nikhil Maan > >> > >> On Tuesday, July 7, 2020 at 5:46:04 AM UTC+5:30, John Yoon wrote: > >>> > >>> Hello, my name is John Yoon, and I would like to express my interest > in contributing to your team for Google’s Season of Docs. Among SymPy’s > various projects, the one focusing on High Level Documentation seems > particularly fascinating and full of potential for innovation. > >>> > >>> > >>> My combined background as both an English major and Computer Science > major would prove useful for the task at hand. Similarly, my prior big data > internship in a research setting at Oregon State University’s Center for > Genome Research and Biocomputing have fostered my Python and data skills. > Furthermore, I currently work as a cloud reliability engineer at NYC’s > cybersecurity agency, which has developed a familiarity working with Git, > as well as documenting my Python implementations of Cloud Functions. > Consequently, I offer a unique perspective with which to approach this > project. > >>> > >>> > >>> My analysis of the project description resulted in a precursory plan > to focus on three primary areas: identifying the most common and useful use > cases of SymPy, develop documentation and tutorials for the aforementioned > cases (i.e., Jupyter notebooks or diagrams), and refactoring any existing > documentation relevant to the most important use cases. Per an earlier > conversation I had with Aaron, I am curious about the team's opinion on > setting the precedence of incorporating Jupyter notebooks into the > project's documentation in order to facilitate more tangible and > interactive tutorials. > >>> > >>> > >>> I would enjoy speaking further about this project to either narrow or > broaden the scope of the team’s documentation endeavors, and to also get a > better understanding of the organization’s workflows and culture. Please > feel free to contact me to discuss further, so I may have a better > understanding of the project prior to the formal application submission > later this week. I have attached my resume and two documentation samples > for your consideration. Thank you. > >>> > >>> > >>> Best, > >>> > >>> John > >> > >> -- > >> You received this message because you are subscribed to the Google > Groups "sympy" group. > >> To unsubscribe from this group and stop receiving emails from it, send > an email to [email protected]. > >> To view this discussion on the web visit > https://groups.google.com/d/msgid/sympy/6f2678f2-178f-4881-83eb-57266506a311o%40googlegroups.com > . > > > > -- > > You received this message because you are subscribed to the Google > Groups "sympy" group. > > To unsubscribe from this group and stop receiving emails from it, send > an email to [email protected]. > > To view this discussion on the web visit > https://groups.google.com/d/msgid/sympy/CAP7f1AgsLj87Fx3GC0T0UmBxRO%2Bxv-st_Ly1R6Zgf9fP4R_kjg%40mail.gmail.com > . > > -- > You received this message because you are subscribed to the Google Groups > "sympy" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/sympy/CAKgW%3D6%2BxSmjm_nvUWEkuLPOY_M%2BE5qr-HD%2Bu6%2Bzt8V_2wXK8MQ%40mail.gmail.com > . > -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAP7f1Ain5a%2B1ce-UhM7jjd9jECTx--dfQPBuO8QEXuLDCBvpTw%40mail.gmail.com.
