Skip to content

GSoD 2020 Ideas

Aaron Meurer edited this page Mar 23, 2020 · 2 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-2020-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. 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

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