Fix up docs

[tannewt]

• Fix badges
• Remove const from address so it doesn't show as mock object.
• Use rst style params
• Mock micropython import
• Remove "Get or set" from properties

(Found these issues based on new Adabot checks.)

[tannewt]

From an email thread with @tdicola:

why the change in language to remove "get and set" for property descriptions?  That's an explicit
decision to make it clear what properties are read-only vs. read-write.  Many of the sensors have
a mix of read-only (acceleration, light, etc.) and read/write properties (gain, data_rate, etc.) so
the documentation is being explicit about what is readable and writable.  Unfortunately RTD
doesn't add this itself even though it's state that Python could presumably parse and infer.

Phrases like "Get or set" and "return" are confusing because they are actions similar to how functions would be described. (Here is an example)It feels ok to say this as the implementer because you know its a function under the hood. However, from the outside, properties are more similar to variables because they represent state. Reading and writing variables is implicit in Python so its unnecessary to call it out.

You make a good point about read-only and I'd suggest using that phrase instead. So for example, DAC value as a 16-bit unsigned value compatible with the AnalogOut class. **Read-only** For read/write properties I think its clearer to omit it than include it. Starting a bunch of properties with the phrase "get or set" or similar is distracting.

[tdicola]

Sorry I don't follow the issue with the language. This is consistent with the API docs we have today, for example DigitalInOut: http://circuitpython.readthedocs.io/en/latest/shared-bindings/digitalio/DigitalInOut.html "Get or set the pin drive mode.", "Get or set the pin pull", etc. AnalogIn: http://circuitpython.readthedocs.io/en/latest/shared-bindings/analogio/AnalogIn.html#analogio.AnalogIn.value "The returned value..." etc.

[tannewt]

Another way to say it is that attributes (whether properties, class attributes or instance attributes) don't do anything on their own so verbs like get, set or return are inappropriate. Instead, attributes are labels for a piece of state and Python provides separate syntax to manipulate that state. The comment should reflect what that state is not what can be done to it.

We have been inconsistent about this in the past and I'd be happy to fix those places as well. MicroPython has lots of "Get or set" comments for their setter/getter functions that we have inherited.

Looking more broadly at how attributes are documented across Python packages I don't see any that say "get or set". Here is where I looked:

• Python's datetime, subprocess
• Numpy's dtype
• Flask's API
• Requests' API

[tdicola]

Yeah this isn't actually state though, it's an I2C transaction that's reading a light level channel from the device. We might give the illusion that it's some state or attribute on an object, but it ultimately is not and can have subtle differences in behavior that need to be documented. For example these light level values are not mutable but the gain values are mutable--the documentation needs to be clear what is readable and what is writable. Removing language like "get" or "set" makes this more difficult to understand. How should a light level that can only be read be described without using the words "get" or "read", or a gain that be both written and read be described without "set", "write", or other verbs?

It's great to look at other documentation but I see plenty of things in those docs that are ambiguous here too:

• Python datetime is explicit about read-only properties--look at the time object, it calls out a separate list of read-only properties and uses the verb "read". Some descriptions even call out the function they're calling internally (utc is described as "timezone(timedelta(0))").
  Subprocess is explicit about read-write vs. read-only (popen.stdin, popen.stdout, etc.).
• dtype by design is immutable so the docs don't have a problem of calling out specific differences (most of numpy is immutable state beyond the ndarray). Look at scipy classes that have mutable state, for example the imageio module that replaced imread: http://imageio.readthedocs.io/en/latest/userapi.html#imageio.core.format.Reader Or look at the most popular image library, PIL/pillow: https://pillow.readthedocs.io/en/latest/reference/Image.html#the-image-class It makes heavy use of get names, "read" verbs, etc. and is very explicit about read-only vs. read-write.
• Flask has APIs like "set_cookie", "get_json", "get_send_file_max_age", etc. Requests has "get_adapter", "get_redirect_target", etc.

This could go on and on looking at different styles, etc. but isn't really productive to do so. In my mind the most important thing is consistency--if our docs today use language like "get" and "set" then I don't see why just this library needs to be the focus of a change. Let's decide on a language and make it a universal change across all the docs. I'm happy to change language but it needs to be clear what is readable and what is readable & writable state to prevent user confusion.

[tannewt]

My decision is to omit verbs from property comments because they are used and documented like attributes. I've been asking for this change on other PRs I've done in the past so some libraries are already done this way. I'm sorry I didn't provide this feedback to you sooner.

Borrowing from this style guide lets use (read-only) and (write-only) at the end of property comments where they are needed. read-write properties are most common so lets omit any additional designation in that case.

I'll follow up this morning with additional explanation in the design guide and fixes for the core docs you pointed out.

[kattni]

As there has been no further response, I'm merging this PR. If further discussion is needed, follow up here, with an issue or create another PR. Thank you.