Thought I was done with doc-comments, but then I noticed that there
wasn't a clear indication in the html about which properties were
settable and which were read only. I also discovered that several
properties that could raise ValueError weren't marked as such.
(technically they were in the code, but Sphinx was ignoring that)
Changes:
1. Systematic :getter: and :setter: attributes for properties
2. Move `:raises: ...` from setter comments to getter comments so
they show up in the html doc. This particularly applies to
setters that use constants.
3. Change `:return: ...` to `:getter: ...` for getter functions
This fixes assorted Sphinx documentation stuff:
1. Add CSS workaround for horizontal stacking glitch in rtd theme
2. Convert plain comments for public constants to doc-comment style
so they will get included in the html docs
3. Change Sphinx autodoc's default sort order from alphabetical to
groupwise. Now the class methods come first, the properties come
next, and the constants go at the end. It's much easier to read
this way.
This commit makes several interrelated changes at once:
1. There's a new lookup table based dB to int7 conversion mechansim
for the analog volume setting properties (based on Table 6-24)
2. Major docs comment revisions for properties involved in DAC
volume, speaker volume, headphone volume, speaker gain, and
headphone gain
3. Added "_" prefix to private helper classes to stop them from
cluttering up the Sphinx html docs build
4. Merged setter & getter comments into the setter comment for
the properties I modified. NOTE: Sphinx does not render docs
comments on property setters!
4. Assorted small-ish revisions to exception handling and
arguments (convert SPK_GAIN_* constants to dB) to resolve
inconsistent or surprising behavior discovered while revising
docs comments
Overall, the goals here are:
1. Make volume setting implementation work and be non-surprising
2. Document how it works
3. Make the TLV320 html docs more readable and complete. A lot of
the docs comment info wasn't making it through into the html
docs build because Sphinx ignores setter comments.
The comments build fine, but it's possible the code has errors.
Saving that testing for another day.
