Pi-top SDK doc strings

pi-top Software
#1

I wonder if its possible to add some doc strings to the pi-top SDK so that users know what things returns/usage information

I went and edited battery.py with some NumPy/SciPi format doc strings just to test and I think something like this would be really handy. Or are you willing for the community to help with it and provide PRs on GitHub for this?

I know some things have doc strings but not everything does

How it looks via VSCode

image
image1280×495 66.9 KB

The Doc strings I added - descriptions of what it returns may not be fully accurate as i can only determine that by what I see happening

image
image820×1006 125 KB

#2

Definitely would like PRs to help with things like this! :+1: Just make sure you conform to the proper docstring standards

#3

Will look into it when I have time and will submit them.

Just wondering which standard are you using since there are a few standards for doc strings

#4

We use the reStructuredText (reST) format - this is used by Sphinx to generate our documentation :+1:

There are some comparisons here actually - it seems that the google style is a bit easier to read and is also compatible with Sphinx with extra configuration. Probably best to stick with reST but I might look into changing this in future

#5

I’m more a numpy person for doc strings but have no problem doing reST doc strings for PRs