Season of Docs 2020 Ideas

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-2020-Ideas.

If you find an idea here interesting and want to discuss it with us, you can contact us on the mailing list.

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. Lauren Glattly's GSoD project created a style guide for SymPy docstrings, which can be found at https://docs.sympy.org/latest/documentation-style-guide.html. The report for that project can be found here.

  However, most docstrings in SymPy still do not follow this guide. The goal of this project would be to update the docstrings throughout SymPy to adhere to this guide. Furthermore, additional improvements could be made to the documentation or the style guide as part of this project. See the Docstring Style Guide milestone on the SymPy issue tracker, as well as the GSoD label.

• 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.

• 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.