Skip to content

GSoD 2019 Ideas

S.Y. Lee edited this page May 9, 2019 · 13 revisions

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.

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

  • 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

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

Clone this wiki locally
You can’t perform that action at this time.