Circuiit Python module description in "Read the Docs" needs
Moderators: adafruit_support_bill, adafruit

Please be positive and constructive with your questions and comments.

Circuiit Python module description in "Read the Docs" needs

by Jerryy on Tue Sep 21, 2021 4:21 pm


I am a new user of CircuitPython with a basic knowledge of digital devices and of the python language. In order to
use some of the products sold by AdaFruit, I decided it would be very usefull to learn the CircuitPython language
since the description of many of these products indicate that they can be run by programs written in that language.

I looked at a number of the sections describing aspects of Circuit Pythan and then tried to understand the sample
programs they contain. For example in the section entitled "CircuitPython Digital In & Out"
at ( https://learn.adafruit.com/circuitpytho ... tal-in-out) it says that the
"digitalio" module is used to manage digital inputs and outputs. Running the code and examining this section a
user can pretty much understand the example code. However assuming that the "digitalio" module would contain
additional options and functionality, I followed the advice at the end of the section that suggested checking out the
"DigitalInOut page" in Read the Docs.

I did so and immediately realized that there is a lot of important information there, but the document seems to assume
that the user has a good deal of background knowledge. Looking at the similar pages for some of the other modules, this
appears to be a common factor. To illustrate what I am talking about the following items on the digitalio module
I believe need to be better defined.

1. The document says that "The digitalio module contains classes to provide access to basic digital IO" but never defines
exactly what it means by "classes".

2. In the first example code there is a line:
pin = digitalio.DigitalInOut(D13) but in the code in the section "CircuitPython Digital In & Out" the analogous line is
led = DigitalInOut(board.LED)

My assumption is that both forms are valid but in a document explaining the language to the novice user, I think if they
are both valid that should be expressly stated.

3. The section "class digitalio.DriveMode:
A. contains the line "Defines the drive mode of digital pin" but does not define what is meant by "drive mode"
B. The next line talks about "Enum-like class" but again what does this mean
C. The section does not define what the 2 values of "Push_Pull" & "Open_Drain" mean.

4. The section "class digitalio.DigitalInOut:
A. What does words "pin: microcontroller.Pin" mean and where is it used?
B. How are the "switch_to_input() and switch_to_output used. Im assuming that if used in a circuit python
script they will cause a pin to flip to being an input or output pin but this is not esplicitly stated or shown in
an example.

There are a number of other areas in the remainder of the document that are similarly not very usable to a user like myself with a
limited knowledge of electrical hardware. In comparison the sections like the one I started with ( ie. "CircuitPython Digital In & Out")
were fairly easy to follow but as I said would only allow to user to contain a limited basic knowledge of CircuitPython.

Any suggestion that anyone can provide to help me better understand and use the Circuiit Python module description in the
"Read the Docs" sections will be greatly appreciated.

Thank You

Jerry Hoffman

Posts: 29
Joined: Thu Feb 22, 2018 9:06 pm

Re: Circuiit Python module description in "Read the Docs" ne

by tannewt on Fri Sep 24, 2021 7:37 pm

Hi Jerry, the Read The Docs are meant more as a reference rather than tutorial like the learn guide. This means that there are some terms we assume folks already know (like "classes" https://docs.python.org/3/tutorial/classes.html) because they are core concepts. For tutorial content I'd suggest sticking to learn guides. They'll do a better job explaining terminology as you need it.

Posts: 2613
Joined: Thu Oct 06, 2016 8:48 pm

Please be positive and constructive with your questions and comments.