Google Season of Docs Ideas list

Note, this is for Google Season of Docs (GSoD). If you are a college student, you are looking for Google Summer of Code (GSoC). See GSoC-2019-Ideas.

SymPy has four main sources of technical writing.

• The SymPy website: https://sympy.org. The sources for this are at https://github.com/sympy/sympy.github.com. The SymPy website has basic information on SymPy and how to obtain it, as well as examples to advertise it to people, but it does not have technical documentation.

• The SymPy documentation: https://docs.sympy.org. This is the main place where people go to learn how to use SymPy. It contains a tutorial for SymPy, as well as technical documentation for all the modules. The sources for this are hosted in the main SymPy repo in the doc directory, and are built using the Sphinx site generator and uploaded to the docs.sympy.org site automatically. The docs website also contains a built in shell (SymPy Live) that allows people to iteratively execute examples.

• The SymPy source code: https://github.com/sympy/sympy. Most functions have documentation attached to it in the form of a "docstring", which explains the function and includes examples, called "doctests". These examples are tested as part of the test suite, so that we know that they always produce the output that they say that they do. Here is an example docstring. Most docstrings are also automatically included in the Sphinx documentation above, so that they appear on https://docs.sympy.org (here is that same docstring on the SymPy website). The docstrings are formatted in a specific way so that Sphinx can render them correctly for the docs website.

  The SymPy sources all contain sparse technical documentation in the form of source code comments, although this does not generally constitute anything substantial.

• The SymPy wiki: https://github.com/sympy/sympy/wiki (where this ideas page is hosted). The SymPy wiki can be edited by anyone. It contains various types of documentation, including:

  • High-level developer documentation (example: https://github.com/sympy/sympy/wiki/Args-Invariant)
  • Guides for new contributors (example: https://github.com/sympy/sympy/wiki/Introduction-to-contributing)
  • Development policies (example: https://github.com/sympy/sympy/wiki/Python-version-support-policy)
  • Release notes (example: https://github.com/sympy/sympy/wiki/Release-Notes-for-1.5)
  • Various pages that different people have added.

SymEngine which is a very fast C++ core that SymPy can optionally use, has some documentation in the doc directory. SymEngine needs a website (right now https://github.com/symengine/symengine points to sympy.org). There is https://symengine.github.io/index.html but it's just doxygen docs, and most of the classes don't have documentation beyond what is generated automatically.

Ideas

• Consistency across docstrings. As noted above, the docstrings in the SymPy source code use a specific formatting so that Sphinx can render them properly. For example, they can have special "see also" sections with lists of similar functions that Sphinx automatically converts into cross references to the corresponding documentation. However, the docstrings across the codebase are not consistent in this formatting. There are also other ways that they could be made consistent beyond formatting, such as the way things are worded and terms that are used. The goal of this project would be to create a guide for documentation that all docstrings in the codebase should follow. It would also involve updating the existing docstrings to follow this guide. Here are some relevant issues

  • https://github.com/sympy/sympy/issues/15370
  • https://github.com/sympy/sympy/issues/12710
  • https://github.com/sympy/sympy/issues/15375
  • https://github.com/sympy/sympy/wiki/Writing-Documentation

• Missing docstrings/doctests. Every public function in SymPy should have a docstring with examples (doctests). At present most do, but some are missing examples or a docstring at all. The goal of this project would be to identify which functions are missing documentation and add it. Similarly, every docstring in SymPy's codebase should be accessible from the Sphinx documentation at https://docs.sympy.org, but some are not. The tool ./bin/coverage_doctest.py in the main SymPy repo can help identify which functions are missing doctests and which functions are not included in Sphinx.

• High level documentation. Most of the documentation in SymPy is in the form of low level documentation for specific functions (in the form of docstrings). We have very few high level guides on how to use specific features. The goal of this project would be to find broad feature set(s) that are missing high level documentation in https://docs.sympy.org and write high level documentation, in the RST format for them. Typically these would involve multiple functions. Examples:

  • A guide on how to use equation solvers in SymPy
  • A guide on simplification functions in SymPy
  • A guide on SymPy's plotting module

• Organization of Documentation The documentation has examples, tutorials, user guides, API declarations, and other various items. Many of these items are mixed together or inconsistently organized. It would be helpful to define all of the types/styles of documentation and organize them in a clear way and define a technical writing guide that helps developers maintain the defined organization.

• Clean up our developer documentation. Right now our developer documentation lives mostly on the wiki. It is very spread out, and some pages are incomplete or outdated. The pages would be cleaned up and put in a more consistent style. It may be more appropriate to move it from the wiki to our main documentation site (this should be discussed with us). This may also include finding places that need better documentation. The discoverability of such documentation should be improved.

• Clean up new contributor documentation. This includes the development guide on the wiki as well as other documents such as

  • https://github.com/sympy/sympy/wiki/Development-workflow (our new contributor guide that has extensive contribution documentation)
  • https://github.com/sympy/sympy/wiki/Introduction-to-contributing (a simpler new contributor intro page that isn't as overwhelming as the main development workflow page)
  • https://github.com/sympy/sympy/wiki/Writing-Release-Notes (guide on writing release notes for pull requests)

  (and others)

  Some of these guides may also need to be rewritten so that they are more appropriate for new contributors. Any gaps in the existing documentation should be identified as well.

  Note that this idea and the previous one are similar to one another.

• SymEngine. Create a webpage with documentation. The documentation should be generated from the source code, probably using Doxygen, and probably converted to Sphinx. Improve the documentation in the source code to look nice.

• Modernizing the SymPy website. https://sympy.org is the main "face" of the SymPy project. It could use some attention and modernization to give it a more professional look and organize the information in an optimal fashion. NumPy recently improved their website (see https://numpy.org) with a modern theme and showcases of downstream projects that highlight NumPy's importance to science and other domains. Some of the ideas they implemented may be useful to implement on SymPy's website. This project would assess the current state and usefulness of the SymPy website, gather user and developer opinion on what could be improved, and update the website with a fresh look, layout, and information.

• Other. If you have an idea that isn't listed on this page, please let us know. We are not technical writers, so we do not necessarily even know in what ways our technical documentation should be improved.