This page summarizes the work carried out during the inaugural Google Season of Docs program for the SymPy project: Consistency Across Docstrings.

I am a freelance technical copy editor working to bring clarity and consistency to documentation and learning materials within the scientific and open source communities.

The main goal of this project was to bring more consistency to SymPy's docstrings. To achieve that goal, this project had three main phases:

1. Identify the desired formatting for a docstring in the codebase.
2. Create a documentation formatting guide for all docstrings across the codebase to follow.
3. Implement the new guide to edit some existing docstrings to serve as a model for all others.

The end goal of completing these three phases was first and foremost to have a SymPy community-approved documentation formatting and style guide which can be used by both developers and contributors to help maintain consistency in SymPy's docstrings now and into the future, as well as an edited docstring(s) that followed the guide to serve as a model for other docstrings in the future.

My mentors and I began the project by discussing at length the desired formatting for SymPy's docstrings. We decided that once the new style guide was in place, while we knew it was not possible to edit all of SymPy's docstrings to match the new guide within the scope of Google Season of Docs, we thought it would be ideal to have a complete submodule's docstrings match the new guide to serve as a model at the end of the project, so we identified a submodule that I could edit once the new style guide was approved.

At the time of the project's start, SymPy had several different resources for information on writing documentation and docstrings, but these resources were not comprehensive and were sometimes conflicting. I worked to synthesize the existing resources to pull out the information that was useful going forward, and compiled it into a draft style guide in a shared Google Doc. At this point, I realized that although the original goal of the project was to simply have a style guide for docstrings, a more comprehensive style guide that including guidelines for narrative documentation as well would be more useful. Because of this, the scope of the style guide changed slightly to become a more comprehensive document. The first draft now included writing guidelines for narrative documentation, a breakdown of the different types of documentation, installation and building the docs instructions, as well as the docstring guidelines as originally planned.

Once the rough draft Google Doc version of the style guide was approved by my mentors, I put it out to the SymPy community on the SymPy Wiki to solicit feedback. After a first round of feedback and editing, I then opened a pull request to merge the style guide with SymPy's documentation and solicit further feedback. After several rounds of feedback and edits, the style guide was approved and merged into SymPy's documentation.

Once the official style guide was in place, I began work editing the submodule my mentors and I had previously identified to implement the new style guide and serve as a model for other docstrings. I opened a pull request for this editing work, which was approved and merged, and went on to edit another file of docstrings which appears as a top hit in a SymPy Google search.

To wrap up the project, I added links to the new style guide in the SymPy READMEs and Wiki pages that are often shared with new community members, so that new and existing SymPy contributors could easily access the SymPy Documentation Style Guide as a writing resource.

This project resulted in an official SymPy Documentation Style Guide that will provide the SymPy community with a set of style and formatting guidelines that can be utilized and followed when writing SymPy documentation. This comprehensive document that is now available as a writing resource will bring greater consistency and clarity to SymPy’s documentation, supporting its mission to become a full-featured, open source computer algebra system (CAS).

The SymPy Documentation Style Guide can be found here: https://docs.sympy.org/dev/documentation-style-guide.html

Here is the merged pull request that shows the addition of the new style guide: https://github.com/sympy/sympy/pull/17715

Here is the merged pull request that shows the edits to the Special submodule that now implements the style guide and can serve as a model for future docstrings: https://github.com/sympy/sympy/pull/17844

Here is the merged pull request that shows edits to the solvers.py file that now implements the style guide: https://github.com/sympy/sympy/pull/17921

Other merged pull requests showing small edits to the READMEs and an update to the style guide:

https://github.com/sympy/sympy/pull/17922

https://github.com/sympy/sympy/pull/17863

While the work of creating an official style guide for SymPy is complete, there is still much work to be done to make all of the docstrings across the codebase follow the new style guide. As part of the project, I edited the Special submodule and solvers.py file to consistently follow the guidelines of the new style guide, but all other docstrings across the codebase must still be edited to comply with the new style guide as well.

Additionally, there was some difficulty in determining the best guidelines in certain situations. One example of this is the choice between the use of LaTeX versus Unicode in docstrings. This decision was difficult to determine because the GSoD team did not always know how SymPy users most frequently access SymPy's documentation and docstrings, and which formatting they find easier to read and understand. In a future Google Season of Doc's program, it would be useful for the technical writer to start with a survey of the community to determine how SymPy's docstrings are most frequently accessed and what kinds of formatting are most beneficial to its users.

This project was a wonderful learning experience for me. I became more comfortable using GitHub, became more knowledgeable and adept at writing in reStructuredText and using Atom as a text editor, and became more comfortable using the command line in terminal. I would like to thank my mentors Aaron Meurer, Jason Moore, and Ondřej Čertík for all of their support and expertise during the course of Google Season of Docs. Thank you!