fix doc build issues; improve doc build error reporting

Author: dhalbert

conf.py

@@ -30,6 +30,7 @@
 from sphinx.transforms import SphinxTransform
 from docutils import nodes
 from sphinx import addnodes
+from sphinx.errors import ConfigError
 from sphinx.ext import intersphinx
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -46,7 +47,12 @@
 # in 'shared-bindings/index.rst'
 
 # The stubs must be built before we calculate the shared bindings matrix
-subprocess.check_output(["make", "stubs"])
+make_stubs = subprocess.run(["make", "stubs"], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+if make_stubs.returncode != 0:
+    print("'ERROR: make stubs' failed with output:", file=sys.stderr)
+    print(make_stubs.stdout.decode("utf-8"))
+    raise ConfigError("'make stubs' failed in conf.py")
+
 
 # modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards()
 modules_support_matrix = shared_bindings_matrix.support_matrix_by_board()
@@ -164,7 +170,7 @@ def autoapi_prepare_jinja_env(jinja_env):
     if git_version:
         final_version = git_version[0]
 else:
-    print("Failed to retrieve git version:", git_describe.stdout)
+    print("Failed to retrieve git version:", git_describe.stdout, file=sys.stderr)
 
 version = release = final_version
 

shared-bindings/audiofreeverb/Freeverb.c

@@ -90,7 +90,7 @@ static mp_obj_t audiofreeverb_freeverb_make_new(const mp_obj_type_t *type, size_
     if (args[ARG_samples_signed].u_bool != true) {
         mp_raise_ValueError_varg(MP_ERROR_TEXT("%q must be %q"), MP_QSTR_samples_signed, MP_QSTR_true);
     }
-    mp_int_t bits_per_sample = mp_arg_validate_int(args[ARG_bits_per_sample].u_int, 16);
+    mp_int_t bits_per_sample = mp_arg_validate_int(args[ARG_bits_per_sample].u_int, 16, MP_QSTR_bits_per_sample);
 
     audiofreeverb_freeverb_obj_t *self = mp_obj_malloc(audiofreeverb_freeverb_obj_t, &audiofreeverb_freeverb_type);
     common_hal_audiofreeverb_freeverb_construct(self, args[ARG_roomsize].u_obj, args[ARG_damp].u_obj, args[ARG_mix].u_obj, args[ARG_buffer_size].u_int, bits_per_sample, args[ARG_samples_signed].u_bool, channel_count, sample_rate);

shared-bindings/usb/util/__init__.c

@@ -20,13 +20,13 @@
 //| This is a subset of the PyUSB util module.
 //| """
 //|
-//| SPEED_LOW: int = ...
+//| SPEED_LOW: int
 //| """A low speed, 1.5 Mbit/s device."""
 //|
-//| SPEED_FULL: int = ...
+//| SPEED_FULL: int
 //| """A full speed, 12 Mbit/s device."""
 //|
-//| SPEED_HIGH: int = ...
+//| SPEED_HIGH: int
 //| """A high speed, 480 Mbit/s device."""
 //|
 

shared-bindings/wifi/Radio.c

@@ -68,7 +68,6 @@ static void validate_hex_password(const uint8_t *buf, size_t len) {
 //|
 //|     This class manages the station and access point functionality of the native
 //|     Wifi radio.
-//|
 //|     """
 //|
 
@@ -79,7 +78,7 @@ static void validate_hex_password(const uint8_t *buf, size_t len) {
 //|
 
 
-//|     def init_airlift(
+//|     def init_airlift(self,
 //|         spi: busio.SPI,
 //|         cs: digitalio.DigitalInOut,
 //|         ready: digitalio.DigitalInOut,
@@ -95,6 +94,8 @@ static void validate_hex_password(const uint8_t *buf, size_t len) {
 //|         :param digitalio.DigitalInOut reset: Reset pin
 //|         :param digitalio.DigitalInOut gpio0: Optional GPIO0 pin for boot mode control
 //|         """
+//|         ...
+//|
 static mp_obj_t wifi_radio_init_airlift(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     #if CIRCUITPY_WIFI_AIRLIFT
     enum { ARG_spi, ARG_cs, ARG_ready, ARG_reset, ARG_gpio0, };
@@ -156,7 +157,7 @@ static void check_for_deinit(wifi_radio_obj_t *self) {
     #endif // CIRCUITPY_WIFI_AIRLIFT
 }
 
-//|     def __enter__(self) -> UART:
+//|     def __enter__(self) -> Radio:
 //|         """No-op used by Context Managers. Only useful on boards that support AirLift `wifi`."""
 //|         ...
 //|
@@ -165,7 +166,7 @@ static void check_for_deinit(wifi_radio_obj_t *self) {
 //|     def __exit__(self) -> None:
 //|         """Automatically deinitializes the hardware when exiting a context. See
 //|         :ref:`lifetime-and-contextmanagers` for more info.
-//|         Only useful on boards that support AirLift `wifi`."""
+//|         Only useful on boards that support AirLift `wifi`.
 //|         """
 //|         ...
 //|
@@ -605,7 +606,6 @@ MP_PROPERTY_GETTER(wifi_radio_ap_active_obj,
 //|         **Limitations**: On AirLift, ``channel`` is ignored.
 //|         On AirLift and on raspberrypi CYW43, ``bssid` is not implemented.
 //|         On AirLift and on raspberrypi CYW43, ``timeout`` is 8 seconds if set to ``None`` or 0.
-//|
 //|         """
 //|         ...
 //|