Swap sphinx to autoapi and the inline stubs

.github/workflows/build.yml

@@ -34,7 +34,7 @@ jobs:
       run: |
         sudo apt-get install -y eatmydata
         sudo eatmydata apt-get install -y gettext librsvg2-bin mingw-w64
-        pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinxcontrib-svg2pdfconverter polib pyyaml
+        pip install requests sh click setuptools cpp-coveralls "Sphinx<4" sphinx-rtd-theme recommonmark sphinx-autoapi sphinxcontrib-svg2pdfconverter polib pyyaml
     - name: Versions
       run: |
         gcc --version

.gitignore

@@ -14,6 +14,7 @@
 ############
 dist/
 *.egg-info
+.eggs
 
 # Logs and Databases
 ######################
@@ -51,6 +52,7 @@ _build
 # Generated rst files
 ######################
 genrst/
+autoapi/
 
 # ctags and similar
 ###################

Makefile

@@ -69,7 +69,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(STUBDIR) $(DISTDIR) *.egg-info
 
-html:
+html: stubs
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -213,8 +213,10 @@ check-translate: locale/circuitpython.pot $(wildcard locale/*.po)
 	$(PYTHON) tools/check_translations.py $^
 
 stubs:
+	mkdir -p circuitpython-stubs
 	python tools/extract_pyi.py shared-bindings/ $(STUBDIR)
-	#python setup.py sdist
+	python tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR)
+	python setup.py sdist
 
 update-frozen-libraries:
 	@echo "Updating all frozen libraries to latest tagged version."

conf.py

@@ -55,7 +55,6 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'rstjinja',
-    'c2rst',
     'recommonmark',
 ]
 
@@ -66,9 +65,17 @@
 source_suffix = {
     '.rst': 'restructuredtext',
     '.md': 'markdown',
-    '.c': ''
 }
 
+extensions.append('autoapi.extension')
+
+autoapi_type = 'python'
+# Uncomment this if debugging autoapi
+# autoapi_keep_files = True
+autoapi_dirs = ['circuitpython-stubs']
+autoapi_add_toctree_entry = False
+autoapi_options = ['members', 'undoc-members', 'private-members', 'show-inheritance', 'special-members', 'show-module-summary']
+autoapi_template_dir = 'docs/autoapi/templates'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -78,7 +85,7 @@
 
 # General information about the project.
 project = 'Adafruit CircuitPython'
-copyright = '2014-2018, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)'
+copyright = '2014-2020, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)'
 
 # These are overwritten on ReadTheDocs.
 # The version info for the project you're documenting, acts as replacement for
@@ -105,6 +112,7 @@
                     ".git",
                     ".venv",
                     ".direnv",
+                    "docs/autoapi",
                     "docs/README.md",
                     "drivers",
                     "examples",

ports/atmel-samd/README.rst

@@ -21,4 +21,4 @@ Port Specific modules
 ---------------------
 
 .. toctree::
-    bindings/samd/__init__
+    ../../autoapi/samd/index

ports/atmel-samd/bindings/samd/Clock.c

@@ -30,18 +30,12 @@
 #include "py/objproperty.h"
 #include "py/runtime.h"
 
-//| .. currentmodule:: samd
+//| import typing
+//| class Clock:
+//|     """Identifies a clock on the microcontroller.
 //|
-//| :class:`Clock` --- Clock reference
-//| ------------------------------------------
-//|
-//| Identifies a clock on the microcontroller.
-//|
-//| .. class:: Clock
-//|
-//|    Identifies a clock on the microcontroller. They are fixed by the
-//|    hardware so they cannot be constructed on demand. Instead, use
-//|    `samd.clock` to reference the desired clock.
+//|        They are fixed by the hardware so they cannot be constructed on demand. Instead, use
+//|        ``samd.clock`` to reference the desired clock."""
 //|
 
 STATIC void samd_clock_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
@@ -50,9 +44,8 @@ STATIC void samd_clock_print(const mp_print_t *print, mp_obj_t self_in, mp_print
     mp_printf(print, "%q.%q.%q", MP_QSTR_samd, MP_QSTR_clock, self->name);
 }
 
-//|     .. attribute:: enabled
-//|
-//|       Is the clock enabled? (read-only)
+//|     enabled: bool = ...
+//|     """Is the clock enabled? (read-only)"""
 //|
 STATIC mp_obj_t samd_clock_get_enabled(mp_obj_t self_in) {
     samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -69,9 +62,8 @@ const mp_obj_property_t samd_clock_enabled_obj = {
     },
 };
 
-//|     .. attribute:: parent
-//|
-//|       Clock parent. (read-only)
+//|     parent: typing.Union(Clock | None) = ...
+//|     """Clock parent. (read-only)"""
 //|
 STATIC mp_obj_t samd_clock_get_parent(mp_obj_t self_in) {
     samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -98,9 +90,8 @@ const mp_obj_property_t samd_clock_parent_obj = {
     },
 };
 
-//|     .. attribute:: frequency
-//|
-//|       Clock frequency. (read-only)
+//|     frequency: int = ...
+//|     """Clock frequency in Herz. (read-only)"""
 //|
 STATIC mp_obj_t samd_clock_get_frequency(mp_obj_t self_in) {
     samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -117,9 +108,8 @@ const mp_obj_property_t samd_clock_frequency_obj = {
     },
 };
 
-//|     .. attribute:: calibration
-//|
-//|       Clock calibration. Not all clocks can be calibrated.
+//|     calibration: int = ...
+//|     """Clock calibration. Not all clocks can be calibrated."""
 //|
 STATIC mp_obj_t samd_clock_get_calibration(mp_obj_t self_in) {
     samd_clock_obj_t *self = MP_OBJ_TO_PTR(self_in);

ports/atmel-samd/bindings/samd/__init__.c

@@ -30,29 +30,16 @@
 
 #include "bindings/samd/Clock.h"
 
-//| :mod:`samd` --- SAMD implementation settings
-//| =================================================
-//|
-//| .. module:: samd
-//|   :synopsis: SAMD implementation settings
-//|   :platform: SAMD21
-//|
-//| Libraries
-//|
-//| .. toctree::
-//|     :maxdepth: 3
-//|
-//|     Clock
-//|
+//| """SAMD implementation settings"""
 
-//| :mod:`samd.clock` --- samd clock names
+//| """:mod:`samd.clock` --- samd clock names
 //| --------------------------------------------------------
 //|
 //| .. module:: samd.clock
 //|   :synopsis: samd clock names
 //|   :platform: SAMD21
 //|
-//| References to clocks as named by the microcontroller
+//| References to clocks as named by the microcontroller"""
 //|
 const mp_obj_module_t samd_clock_module = {
     .base = { &mp_type_module },

setup.py

@@ -5,18 +5,16 @@
 stub_root = Path("circuitpython-stubs")
 stubs = [p.relative_to(stub_root).as_posix() for p in stub_root.glob("*.pyi")]
 
-now = datetime.utcnow()
-version = now.strftime("%Y.%m.%d")
-
 setup(
     name="circuitpython-stubs",
     description="PEP 561 type stubs for CircuitPython",
     url="https://github.com/adafruit/circuitpython",
     maintainer="CircuitPythonistas",
     author_email="[email protected]",
-    version=version,
+    use_scm_version=True,
     license="MIT",
     package_data={"circuitpython-stubs": stubs},
     packages=["circuitpython-stubs"],
-    setup_requires=["setuptools>=38.6.0"],
+    setup_requires=["setuptools>=38.6.0",
+                    "setuptools_scm"],
 )

shared-bindings/_bleio/Adapter.c

@@ -48,10 +48,7 @@
 #define WINDOW_DEFAULT (0.1f)
 
 //| class Adapter:
-//|     """.. currentmodule:: _bleio
-//|
-//|     :class:`Adapter` --- BLE adapter
-//|     ----------------------------------------------------
+//|     """BLE adapter
 //|
 //|     The Adapter manages the discovery and connection to other nearby Bluetooth Low Energy devices.
 //|     This part of the Bluetooth Low Energy Specification is known as Generic Access Profile (GAP).

shared-bindings/_bleio/Address.c

@@ -35,12 +35,7 @@
 #include "shared-module/_bleio/Address.h"
 
 //| class Address:
-//|     """.. currentmodule:: _bleio
-//|
-//|     :class:`Address` -- BLE address
-//|     =========================================================
-//|
-//|     Encapsulates the address of a BLE device."""
+//|     """Encapsulates the address of a BLE device."""
 //|
 
 //|     def __init__(self, address: buf, address_type: Any):
@@ -97,7 +92,7 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args,
 //|       >>> _bleio.adapter.address
 //|       <Address c8:1d:f5:ed:a8:35>
 //|       >>> _bleio.adapter.address.address_bytes
-//|       b'5\xa8\xed\xf5\x1d\xc8'"""
+//|       b'5\\xa8\\xed\\xf5\\x1d\\xc8'"""
 //|
 STATIC mp_obj_t bleio_address_get_address_bytes(mp_obj_t self_in) {
     bleio_address_obj_t *self = MP_OBJ_TO_PTR(self_in);

shared-bindings/_bleio/Attribute.c

@@ -30,12 +30,8 @@
 #include "shared-bindings/_bleio/UUID.h"
 
 //| class Attribute:
-//|     """.. currentmodule:: _bleio
+//|     """Definitions associated with all BLE attributes: characteristics, descriptors, etc.
 //|
-//|     :class:`Attribute` -- BLE Attribute
-//|     =========================================================
-//|
-//|     Definitions associated with all BLE attributes: characteristics, descriptors, etc.
 //|     :py:class:`~_bleio.Attribute` is, notionally, a superclass of
 //|     :py:class:`~Characteristic` and :py:class:`~Descriptor`,
 //|     but is not defined as a Python superclass of those classes."""

shared-bindings/_bleio/Characteristic.c

@@ -34,13 +34,8 @@
 #include "shared-bindings/_bleio/UUID.h"
 
 //| class Characteristic:
-//|     """.. currentmodule:: _bleio
-//|
-//|     :class:`Characteristic` -- BLE service characteristic
-//|     =========================================================
-//|
-//|     Stores information about a BLE service characteristic and allows reading
-//|     and writing of the characteristic's value."""
+//|     """Stores information about a BLE service characteristic and allows reading
+//|        and writing of the characteristic's value."""
 //|
 //|     def __init__(self, ):
 //|         """There is no regular constructor for a Characteristic. A new local Characteristic can be created

shared-bindings/_bleio/CharacteristicBuffer.c

@@ -42,12 +42,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self
 }
 
 //| class CharacteristicBuffer:
-//|     """.. currentmodule:: _bleio
-//|
-//|     :class:`CharacteristicBuffer` -- BLE Service incoming values buffer.
-//|     =====================================================================
-//|
-//|     Accumulates a Characteristic's incoming values in a FIFO buffer."""
+//|     """Accumulates a Characteristic's incoming values in a FIFO buffer."""
 //|
 //|     def __init__(self, characteristic: Characteristic, *, timeout: int = 1, buffer_size: int = 64):
 //|

shared-bindings/_bleio/Connection.c

@@ -43,12 +43,7 @@
 #include "shared-bindings/_bleio/Service.h"
 
 //| class Connection:
-//|     """.. currentmodule:: _bleio
-//|
-//|     :class:`Connection` -- A BLE connection
-//|     =========================================================
-//|
-//|     A BLE connection to another device. Used to discover and interact with services on the other
+//|     """A BLE connection to another device. Used to discover and interact with services on the other
 //|     device.
 //|
 //|     Usage::
@@ -211,15 +206,14 @@ STATIC mp_obj_t bleio_connection_get_connection_interval(mp_obj_t self_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_connection_get_connection_interval_obj, bleio_connection_get_connection_interval);
 
-//|   .. attribute:: max_packet_length
-//|
-//|     The maximum number of data bytes that can be sent in a single transmission,
+//|     attribute: Any = ...
+//|     """The maximum number of data bytes that can be sent in a single transmission,
 //|     not including overhead bytes.
 //|
 //|     This is the maximum number of bytes that can be sent in a notification,
 //|     which must be sent in a single packet.
 //|     But for a regular characteristic read or write, may be sent in multiple packets,
-//|     so this limit does not apply.
+//|     so this limit does not apply."""
 //|
 STATIC mp_obj_t bleio_connection_get_max_packet_length(mp_obj_t self_in) {
     bleio_connection_obj_t *self = MP_OBJ_TO_PTR(self_in);

shared-bindings/_bleio/Descriptor.c

@@ -34,12 +34,8 @@
 #include "shared-bindings/_bleio/UUID.h"
 
 //| class Descriptor:
-//|     """.. currentmodule:: _bleio
+//|     """Stores information about a BLE descriptor.
 //|
-//|     :class:`Descriptor` -- BLE descriptor
-//|     =========================================================
-//|
-//|     Stores information about a BLE descriptor.
 //|     Descriptors are attached to BLE characteristics and provide contextual
 //|     information about the characteristic."""
 //|