improving docs and varia

[jposada202020]

improving docs
including learning guides, and ICM20948 breakout in hardware API.
Including all examples in API.
Re-arranging class doc order in api.rst

Built locally to verify

[dhalbert]

@jposada202020 Thank you for doing these improvements to multiple libraries.

A couple of comments which apply to most of these PR's:

The phrasing "Here is one way of importing the MCP9600 class so you can use it with the name mcp", and similar sort of suggest to me there's something special about the name mcp. I might rewrite this as "Here is an example of creating and using an MCP9600 object, assigning it to the variable mcp." Or even just "Here is an example of using the MCP9600 class."

We often recommend people use board.I2C() instead of busio.I2C(board.SCL, board, SDA). It's a common support issue that people try to create multiple instances of busio.I2C(board.SCL, board, SDA) and are confused by the errors on the second try. The advantage of using board.I2C() is that this problem is avoided. The disadvantage is that it's not clear which pins are being used, though that could be in a comment, e.g.:

i2c = board.I2C()    # Uses board.SCL and board.SDA

Many of the simpletests were written before board.I2C() existed. @kattni, do you have a comment about whether board.I2C() or busio.I2C() would be preferred for these simple examples?

[jposada202020]

@dhalbert Thanks for the comments. good points

1. I will modify the phrasing according to your recommendations. Thanks
2. Regarding the use of busio. A lot of the examples use busio. A lot of learning guides use it also in the example code.

One Example

https://learn.adafruit.com/lsm6ds33-6-dof-imu=accelerometer-gyro/python-circuitpython
Let me know what will be the correct way and I will use it.
Questions?
Would this imply to correct the simpletest_code also?. (I do not have all these hardware to test if after the changes, the library will work)

I would wait until guidance is given before continuing the update. Thanks

[dhalbert]

I would wait until guidance is given before continuing the update.

We could discuss this In the Weeds in the weekly meeting tomorrow.

[jposada202020]

Yes good Idea 😃 I was hearing our meeting on feb 8th. regarding a similar topic. That was regarding this issue adafruit/circuitpython#4121. I will add this to the offtopic to the meeting thanks Dan

[jposada202020]

@dhalbert as discussed in our meeting I made the changes. Hope everything is in there, if not please comment and I will correct accordingly. Thanks again for the support

[jposada202020]

After reflecting on this on the param descriptio we could use

:param ~busio.I2C i2c_bus:`

when I use ~board.I2C it does not show as a Hyperlink in the documentation, do you know a way to make the correct reference?

[jposada202020]

@dhalbert I went through the Sphinx documentation twice? trying to find a solution for the parameter..no luck also tried different things, it seems that when we try to get the objects.inv from the documentation in readthedocs while building the api docs we could not get the correct information from the class objects. (I suppose, this is because board.I2C are not a class, could be way wrong). So I am returning to the parameter definition as ~busio.I2C. The examples and the readme.rst for sure I would change to board.I2C().
Anyway if you have some time to review this, it would be really appreciate it, I would like to get this ball rolling over the weekend Thanks 😃

[kattni]

Please check through this and correct the use of slave to peripheral where used. Thanks!

[kattni]

Please update the use of the word slave here to peripheral to match the CircuitPython Design Guide terminology.

[jposada202020]

Will do thanks :)

[jposada202020]

I will go back and correct this and all the busio designations in previous PRs. Thanks @kattni

[jposada202020]

@kattni I updated this according to your suggestion and will continue to use the design guide for the comments

[jposada202020]

This is solved in 5c27ce9