Re: Season of Docs - High Level Documentation
62 views
Skip to first unread message
Message has been deleted
Nikhil Maan
Jul 7, 2020, 2:16:43 PM7/7/20
to sympy
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:
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
John Yoon
Jul 7, 2020, 3:26:16 PM7/7/20
to sympy
My tutorials/guides would primarily focus on classical machine learning and data science problems. There are several Kaggle beginner projects (i.e. housing price prediction through regression, or image classification) that are implemented through Python and the usual popular libraries like numpy, matplotlib, etc. Through my Season of Docs project, I would take those implementations and step-by-step translate them into SymPy to achieve similar results. This process should highlight several of the most common use cases of SymPy's user base, and help new adopters to transition more smoothly.
Jason Moore
Jul 7, 2020, 3:29:15 PM7/7/20
to sympy
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
--
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 sympy+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/6f2678f2-178f-4881-83eb-57266506a311o%40googlegroups.com.
Jason Moore
Jul 7, 2020, 3:30:06 PM7/7/20
to sympy
John,
One issue with your proposal is that SymPy doesn't (at least explicitly) do any of the things you mention.
Jason
--
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 sympy+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/18abc6c6-af2a-4f3a-a69f-47669339602co%40googlegroups.com.
John Yoon
Jul 7, 2020, 3:38:33 PM7/7/20
to sympy
My apologies if I do not fully understand, but could you clarify what you mean?
I was of the belief that SymPy possessed features relating to topics such as differential equations which might be used in the context of situations dealing with regressions.
Best,
John
To unsubscribe from this group and stop receiving emails from it, send an email to sy...@googlegroups.com.
Jason Moore
Jul 7, 2020, 3:52:36 PM7/7/20
to sympy
John,
I recommend doing the SymPy tutorial (if you haven't) to get a sense of what SymPy does: https://docs.sympy.org/latest/tutorial/
Jason
To unsubscribe from this group and stop receiving emails from it, send an email to sympy+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/45437afa-8afa-4187-9485-b6ad643d9a43o%40googlegroups.com.
Aaron Meurer
Jul 7, 2020, 4:05:30 PM7/7/20
to sympy
On Tue, Jul 7, 2020 at 1:29 PM Jason Moore <moore...@gmail.com> 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
>
> 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.
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
Jason Moore
Jul 7, 2020, 4:13:09 PM7/7/20
to sympy
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
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.
Aaron Meurer
Jul 7, 2020, 4:22:12 PM7/7/20
to sympy
I didn't realize that thebelab requires jupyter-sphinx. That limits
its usefulness. It is a very interesting project and I hope we can
someday replace SymPy Live with either it or something like it.
Aaron Meurer
> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAP7f1Ain5a%2B1ce-UhM7jjd9jECTx--dfQPBuO8QEXuLDCBvpTw%40mail.gmail.com.
its usefulness. It is a very interesting project and I hope we can
someday replace SymPy Live with either it or something like it.
Aaron Meurer
Aaron Meurer
Jul 7, 2020, 4:24:00 PM7/7/20
to sympy
The documentation for thebelab says it can strip prompts, which
suggests that it would work for normal doctest-type code examples like
we use in SymPy's docs. I guess we would need to play around with it.
Aaron Meurer
suggests that it would work for normal doctest-type code examples like
we use in SymPy's docs. I guess we would need to play around with it.
Aaron Meurer
Jason Moore
Jul 7, 2020, 4:43:05 PM7/7/20
to sympy
> I didn't realize that thebelab requires jupyter-sphinx.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6J6_iXyTvsOP8pjVD0xqTBQzWxo5t_LDaBP6wrbGbC1%2BA%40mail.gmail.com.
Jason Moore
Jul 7, 2020, 4:43:50 PM7/7/20
to sympy
I think SymPy live is better than Thebelab because it doesn't require the long startup time for the binder/docker container build.
Jason
Reply all
Reply to author
Forward
0 new messages