level up documentation comments

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.

Author: samblenny

adafruit_tlv320.py

@@ -15,6 +15,11 @@
 
 **Hardware:**
 
+* `Adafruit TLV320DAC3100 - I2S DAC <https://www.adafruit.com/product/6309>`_
+
+* `Adafruit Fruit Jam <https://www.adafruit.com/product/6200>`_
+
+
 * The TLV320DAC chip has moderately complex onboard audio filtering, routing,
   and amplification capability. Each of the signal chains for speaker, headphone
   left, and headphone right start with the DAC, then they go through a mixer
@@ -122,56 +127,92 @@
 DATA_LEN_32 = const(0b11)  # 32 bits
 
 # GPIO1 pin mode options
-GPIO1_DISABLED = const(0b0000)  # GPIO1 disabled (input and output buffers powered down)
-GPIO1_INPUT_MODE = const(0b0001)  # Input mode (secondary BCLK/WCLK/DIN input or ClockGen)
-GPIO1_GPI = const(0b0010)  # General-purpose input
-GPIO1_GPO = const(0b0011)  # General-purpose output
-GPIO1_CLKOUT = const(0b0100)  # CLKOUT output
-GPIO1_INT1 = const(0b0101)  # INT1 output
-GPIO1_INT2 = const(0b0110)  # INT2 output
-GPIO1_BCLK_OUT = const(0b1000)  # Secondary BCLK output for codec interface
-GPIO1_WCLK_OUT = const(0b1001)  # Secondary WCLK output for codec interface
+#: GPIO1 pin mode options: GPIO1 disabled (input and output buffers powered down)
+GPIO1_DISABLED = const(0b0000)
+#: GPIO1 pin mode options: Input mode (secondary BCLK/WCLK/DIN input or ClockGen)
+GPIO1_INPUT_MODE = const(0b0001)
+#: GPIO1 pin mode options: General-purpose input
+GPIO1_GPI = const(0b0010)
+#: GPIO1 pin mode options: General-purpose output
+GPIO1_GPO = const(0b0011)
+#: GPIO1 pin mode options: CLKOUT output
+GPIO1_CLKOUT = const(0b0100)
+#: GPIO1 pin mode options: INT1 output
+GPIO1_INT1 = const(0b0101)
+#: GPIO1 pin mode options: INT2 output
+GPIO1_INT2 = const(0b0110)
+#: GPIO1 pin mode options: Secondary BCLK output for codec interface
+GPIO1_BCLK_OUT = const(0b1000)
+#: GPIO1 pin mode options: Secondary WCLK output for codec interface
+GPIO1_WCLK_OUT = const(0b1001)
 
 # DAC channel data path options
-DAC_PATH_OFF = const(0b00)  # DAC data path off
-DAC_PATH_NORMAL = const(0b01)  # Normal path (L->L or R->R)
-DAC_PATH_SWAPPED = const(0b10)  # Swapped path (R->L or L->R)
-DAC_PATH_MIXED = const(0b11)  # Mixed L+R path
+#: DAC channel data path option: DAC data path off
+DAC_PATH_OFF = const(0b00)
+#: DAC channel data path option: Normal path (L->L or R->R)
+DAC_PATH_NORMAL = const(0b01)
+#: DAC channel data path option: Swapped path (R->L or L->R)
+DAC_PATH_SWAPPED = const(0b10)
+#: DAC channel data path option: Mixed L+R path
+DAC_PATH_MIXED = const(0b11)
 
 # DAC volume control soft stepping options
-VOLUME_STEP_1SAMPLE = const(0b00)  # One step per sample
-VOLUME_STEP_2SAMPLE = const(0b01)  # One step per two samples
-VOLUME_STEP_DISABLED = const(0b10)  # Soft stepping disabled
+#: DAC volume control soft stepping option: One step per sample
+VOLUME_STEP_1SAMPLE = const(0b00)
+#: DAC volume control soft stepping option: One step per two samples
+VOLUME_STEP_2SAMPLE = const(0b01)
+#: DAC volume control soft stepping option: Soft stepping disabled
+VOLUME_STEP_DISABLED = const(0b10)
 
 # DAC volume control configuration options
-VOL_INDEPENDENT = const(0b00)  # Left and right channels independent
-VOL_LEFT_TO_RIGHT = const(0b01)  # Left follows right volume
-VOL_RIGHT_TO_LEFT = const(0b10)  # Right follows left volume
+#: DAC volume control configuration option: Left and right channels independent
+VOL_INDEPENDENT = const(0b00)
+#: DAC volume control configuration option: Left follows right volume
+VOL_LEFT_TO_RIGHT = const(0b01)
+#: DAC volume control configuration option: Right follows left volume
+VOL_RIGHT_TO_LEFT = const(0b10)
 
 # DAC output routing options
-DAC_ROUTE_NONE = const(0b00)  # DAC not routed
-DAC_ROUTE_MIXER = const(0b01)  # DAC routed to mixer amplifier
-DAC_ROUTE_HP = const(0b10)  # DAC routed directly to HP driver
-
-# Headphone common mode voltage settings
-HP_COMMON_1_35V = const(0b00)  # Common-mode voltage 1.35V
-HP_COMMON_1_50V = const(0b01)  # Common-mode voltage 1.50V
-HP_COMMON_1_65V = const(0b10)  # Common-mode voltage 1.65V
-HP_COMMON_1_80V = const(0b11)  # Common-mode voltage 1.80V
+#: DAC output routing option: DAC not routed
+DAC_ROUTE_NONE = const(0b00)
+#: DAC output routing option: DAC routed to mixer amplifier
+DAC_ROUTE_MIXER = const(0b01)
+#: DAC output routing option: DAC routed directly to HP driver
+DAC_ROUTE_HP = const(0b10)
+
+# Headphone common mode voltage options
+#: Headphone common mode voltage option: Common-mode voltage 1.35V
+HP_COMMON_1_35V = const(0b00)
+#: Headphone common mode voltage option: Common-mode voltage 1.50V
+HP_COMMON_1_50V = const(0b01)
+#: Headphone common mode voltage option: Common-mode voltage 1.65V
+HP_COMMON_1_65V = const(0b10)
+#: Headphone common mode voltage option: Common-mode voltage 1.80V
+HP_COMMON_1_80V = const(0b11)
 
 # Headset detection debounce time options
-DEBOUNCE_16MS = const(0b000)  # 16ms debounce (2ms clock)
-DEBOUNCE_32MS = const(0b001)  # 32ms debounce (4ms clock)
-DEBOUNCE_64MS = const(0b010)  # 64ms debounce (8ms clock)
-DEBOUNCE_128MS = const(0b011)  # 128ms debounce (16ms clock)
-DEBOUNCE_256MS = const(0b100)  # 256ms debounce (32ms clock)
-DEBOUNCE_512MS = const(0b101)  # 512ms debounce (64ms clock)
+#: Headset detection debounce time option: 16ms debounce (2ms clock)
+DEBOUNCE_16MS = const(0b000)
+#: Headset detection debounce time option: 32ms debounce (4ms clock)
+DEBOUNCE_32MS = const(0b001)
+#: Headset detection debounce time option: 64ms debounce (8ms clock)
+DEBOUNCE_64MS = const(0b010)
+#: Headset detection debounce time option: 128ms debounce (16ms clock)
+DEBOUNCE_128MS = const(0b011)
+#: Headset detection debounce time option: 256ms debounce (32ms clock)
+DEBOUNCE_256MS = const(0b100)
+#: Headset detection debounce time option: 512ms debounce (64ms clock)
+DEBOUNCE_512MS = const(0b101)
 
 # Button press debounce time options
-BTN_DEBOUNCE_0MS = const(0b00)  # No debounce
-BTN_DEBOUNCE_8MS = const(0b01)  # 8ms debounce (1ms clock)
-BTN_DEBOUNCE_16MS = const(0b10)  # 16ms debounce (2ms clock)
-BTN_DEBOUNCE_32MS = const(0b11)  # 32ms debounce (4ms clock)
+#: Button press debounce time option: No debounce
+BTN_DEBOUNCE_0MS = const(0b00)
+#: Button press debounce time option: 8ms debounce (1ms clock)
+BTN_DEBOUNCE_8MS = const(0b01)
+#: Button press debounce time option: 16ms debounce (2ms clock)
+BTN_DEBOUNCE_16MS = const(0b10)
+#: Button press debounce time option: 32ms debounce (4ms clock)
+BTN_DEBOUNCE_32MS = const(0b11)
 
 # Lookup table for speaker_volume and headphone_volume.
 # These are from TLV320DAC3100 datasheet Table 6-24.

docs/_static/custom.css

@@ -0,0 +1,4 @@
+/* Monkey patch the rtd theme to prevent horizontal stacking of short items
+ * see https://github.com/readthedocs/sphinx_rtd_theme/issues/1301
+*/
+.py.property{display: block !important;}

docs/conf.py

@@ -29,6 +29,9 @@
 
 autodoc_preserve_defaults = True
 
+# Override the default config in which autodoc sorts things alphabetically
+autodoc_member_order = 'groupwise'
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "BusDevice": ("https://docs.circuitpython.org/projects/busdevice/en/latest/", None),
@@ -117,6 +120,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+# Include extra css to work around rtd theme glitches
+html_css_files = ['custom.css']
+
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.