I added these several commits back because they seemed to resolve
a weird Sphinx code-block rendering bug in the html docs. But, now
I can't reproduce the bug, so there's no reason to keep the
escapes.
This fixes a bug that I found while testing the speaker output. I
also balanced the default speaker_volume and headphone_volume gain
levels so they sound about the same loudness (to me, with my
earbuds). That way you can use dac_volume for runtime volume
adjustments and it will hopefully work about the same for the
speaker or the headphones.
To set the board up for different headphones or speakers, you could
experiment with suitable values for speaker_volume and
headphone_volume to set in an initialization function, like a
trimpot. After that, you could use dac_volume to set volume.
This fixes the headphone_output property setter to use the
DAC_ROUTE_MIXER option so the headphone_volume attenuation stage
doesn't get bypassed (as it did previously). This makes it a lot
easier to set non-ear-bleedy volume levels for headphones.
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.
