This page contains the details of a technical writing project accepted for Season of Docs.
- Open source organization:
- Technical writer:
- Project name:
- Consistency across docstrings - Sympy documentation
- Project length:
- Standard length (3 months)
Current State of Sympy Documentation and previous work :
The work of creating an official style guide for SymPy is complete.
Lauren Glattly's GSoD project created a style guide for SymPy docstrings, which can be found at SymPy Documentation Style Guide.
The docstrings in Special submodule and solvers.py file were edited to consistently follow the guidelines of the new style guide
All other docstrings across the codebase were still to be edited to comply with the new style guide as well.
Proposed Work :
Most docstrings in SymPy still do not follow the latest style guide. The goal of this project would be to update the docstrings throughout SymPy to adhere to this guide.
I discussed the project with mentors. Here is a link to the discussion.
It was decided that editing docstrings throughout sympy’s codebase to adhere to the latest style guide is a big task and the project should be limited to it.
My work on the project would involve implementing the new guide to update existing docstrings, while collecting and addressing other inconsistencies such as language use or terms.
The order of existing subsections can be changed or decided later or as a separate task.
Demonstrating the differences in results when different values are passed to parameters by adding more examples along with addition of parameters section.
Keep adding tricky examples to the gotchas and pitfalls section.
Contributions: - #17887 : Worked on issue #17887: Add missing docstring sections in Special submodule. I added the missing Parameters and Examples section in some functions of the Specials submodule which was edited by L. Glattly to follow the latest style guide and serve as a model for future docstrings.
Here is the link to my merged PR : https://github.com/sympy/sympy/pull/19334
- #19591 : Issue #19591 tracks the Documentation style guide. I added a PR to edit the core.sympify docstring to adhere to the latest style guide. I have added structured explanations and examples on the usage of different parameters.
Here is a link to the PR: https://github.com/sympy/sympy/pull/19613
Timeline Before August 17 :
- Continue making contributions to the organization.
- Become more familiar with the user documentation and current version of sympy.
- Learn techniques and skills which will be helpful while implementing the project.
Community bonding : (August 17 - September 13, 2020)
- Set up a communication channel and time (due to time difference).
- Refine my goals and set expectations on both sides.
- Discussing the order in which the modules will be updated.
- Finalize the order of editing modules to make them adhere to the latest docstring style guide.
Documentation Period(September 14, 2020 - November 30, 2020) :
Set goals to achieve every week, preferably complete updating docstrings of one module or submodule per week or more.
For all these modules, my primary goal will be to add missing sections and restructure the docstrings to follow the latest style guide. This will include demonstrating the different results obtained when different values are passed to the parameters. All tricky outputs shall be added to the Gotchas and Pitfalls section.
Week 1 ( September 14 - September 21) : Core
Week 2 (September 22 - September 29) : Functions : Submodules Combinatorial
Week 3 (30 September - 6th October) : Functions
Week 4 (7th October - 14th October) : Simplify, Crypto
Week 5 (15th October - 21th October) : Diophantine
Week 6 (22st October - 29th October):Holonomic :Operations submodule
Week 7 (30 th October - 7th November) : Integrals Module(integrals.integrals), Computing Integrals using Meijer G-Functions
Week 8 (8st November - 15th November) : Physics, Functions at the end of Categories Module, Code Generation Module, Submodule Special
Week 9 (16th November - 23 rd November) : Physics, Functions at the end of Categories Module, Code Generation Module, Submodule Special
Week 10 (24th November - 30th November) : Gotchas and Pitfalls section
November 30 - December 5, 2020 at 18:00 UTC : Final Project submission and Report Writing
December 3 - 10, 2020 at 18:00 UTC : Submission of success of project and experience of working with mentors
The order of the modules mentioned here can be changed after further discussion with mentors.
As suggested by mentors, I will focus on updating those modules first which are easier to update, then move on to the complex ones.
Why am I the right person for this project?
I believe myself to be the right person for this project because I have past experience in technical writing with Computer Science and I am well versed with git and github.
As I have submitted PRs to update documentation to the latest style guide in sympy which have been successfully merged, I am confident with the workflow and making regular contributions.
Initially when I started contributing, I faced some errors. I finally got used to running the tests and building the docs everytime before committing the changes as that is very important.
I am very comfortable in contributing to this project and am looking forward to it.