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. - 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 > <https://groups.google.com/d/msgid/sympy/6f2678f2-178f-4881-83eb-57266506a311o%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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.
