Blog 2 : Embracing the Struggle
While everyone struggles , I chose to embrace the struggle.
Hello everyone, I am here again with the 2nd Blog of my journey as an Outreachy intern. For those who don't know me , I am Neelima Mohanty , selected as an Outreachy intern at Humanitarian OpenStreetMap Team (HOTOSM) for the May to August Cohort. If you are new to my blog then make sure you read my Blog 1 before going through this blog post.
How many of you have come across new terms while contributing to open source communities? I guess everyone has . And do you remember how did you cope with it? As you think of all this , I will narrate you one such experience of mine during the contribution phase of Outreachy during March 2023 .
While raising a PR to add comments to the code of the osm-fieldwork repo as part of technical documentation , my mentor Rob Savoye reviewed it and said me that he liked the thought of adding comments to the code but it was not the right way. I would like to quote his words “Thanks for adding comments. We usually don't need to comment write() and open(), as it's obvious. If you want to get really deep into commenting source code, we want to add support for sphinx.This adds a comment block for each class and method. This would require you read and gain some understanding of the code itself, which is not a bad thing. We use sphinx for other python projects.”
On researching according to his words , I came across a new term “Auto-Documentation” which is also known as “auto-docs” in short. Then I raised an issue on adding auto-docs to the source code using sphinx so that Rob and other members of the HOTOSM community could respond . Reading this one of the important members of Humanitarian OpenStreetMap Team , Sam Woodcock said “My recommendation would be mkdocs instead of Sphinx. I have always found it much easier to implement and manage.Plus it's nice to have readable markdown at the end, rather than reStructuredText.The docstrings can be in any style: Google (my choice), numpy, reStructuredText.This would only be a change to the auto documentation tooling.It would be great to update the function parameters at the same time to include type hinting (as this helps auto doc generation).”.
Having the suggestions of both Rob and Sam , I researched and learnt a lot of subtopics coming under the topic “Auto-docs” such as “docstrings” and “type hinting”. I researched on how to implement auto-docs using mkdocs and sphinx. While the research on using which of the above two will be best for our code is still on and I will be updating you on it in one of the upcoming blogs but one thing is clear that “Auto-Documentation” was the first new vocabulary term I have learnt after I applied to Outreachy.
For those who are also new to this term , I am sharing below links to a few resources which have helped me and will help you too .
- https://towardsdatascience.com/auto-docs-for-python-b545ce372e2d
- https://www.sphinx-doc.org/en/master/
- https://www.mkdocs.org/
At the end of this blog , I want to thank my mentor Rob Savoye and also Sam Woodcock for playing major roles in making me learn such a wonderful part of technical documentation . I would also like to thank my mentors Rob Savoye and Petya Kangalova again for being with me and assisting me at every step of my journey as an intern since the last two weeks. That's it friends , meet you next time with Blog 3. Till then bye 😊
People who read this also read
