Merge pull request #3252 from ciscorn/pyi

Some improvements to the core module docs

Author: jepler

Makefile

@@ -245,6 +245,10 @@ stubs:
 	@$(PYTHON) tools/extract_pyi.py ports/atmel-samd/bindings $(STUBDIR)
 	@$(PYTHON) setup.py -q sdist
 
+.PHONY: check-stubs
+check-stubs: stubs
+	MYPYPATH=$(STUBDIR) mypy --strict $(STUBDIR)
+
 update-frozen-libraries:
 	@echo "Updating all frozen libraries to latest tagged version."
 	cd frozen; for library in *; do cd $$library; ../../tools/git-checkout-latest-tag.sh; cd ..; done

conf.py

@@ -17,7 +17,6 @@
 #
 # SPDX-License-Identifier: MIT
 
-import json
 import logging
 import os
 import re
@@ -26,6 +25,9 @@
 import urllib.parse
 
 import recommonmark
+from sphinx.transforms import SphinxTransform
+from docutils import nodes
+from sphinx import addnodes
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -85,6 +87,7 @@
 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'
+autoapi_python_class_content = "both"
 autoapi_python_use_implicit_namespaces = True
 autoapi_root = "shared-bindings"
 
@@ -442,7 +445,38 @@ def generate_redirects(app):
             with open(redirected_filename, 'w') as f:
                 f.write(TEMPLATE % urllib.parse.quote(to_path, '#/'))
 
+
+class CoreModuleTransform(SphinxTransform):
+    default_priority = 870
+
+    def _convert_first_paragraph_into_title(self):
+        title = self.document.next_node(nodes.title)
+        paragraph = self.document.next_node(nodes.paragraph)
+        if not title or not paragraph:
+            return
+        if isinstance(paragraph[0], nodes.paragraph):
+            paragraph = paragraph[0]
+        if all(isinstance(child, nodes.Text) for child in paragraph.children):
+            for child in paragraph.children:
+                title.append(nodes.Text(" \u2013 "))
+                title.append(child)
+            paragraph.parent.remove(paragraph)
+
+    def _enable_linking_to_nonclass_targets(self):
+        for desc in self.document.traverse(addnodes.desc):
+            for xref in desc.traverse(addnodes.pending_xref):
+                if xref.attributes.get("reftype") == "class":
+                    xref.attributes.pop("refspecific", None)
+
+    def apply(self, **kwargs):
+        docname = self.env.docname
+        if docname.startswith(autoapi_root) and docname.endswith("/index"):
+            self._convert_first_paragraph_into_title()
+            self._enable_linking_to_nonclass_targets()
+
+
 def setup(app):
     app.add_css_file("customstyle.css")
     app.add_config_value('redirects_file', 'redirects', 'env')
     app.connect('builder-inited', generate_redirects)
+    app.add_transform(CoreModuleTransform)

docs/autoapi/templates/python/module.rst

@@ -18,8 +18,7 @@
 {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
 {% if visible_subpackages %}
 .. toctree::
-   :titlesonly:
-   :maxdepth: 3
+   :maxdepth: 2
 
 {% for subpackage in visible_subpackages %}
    {{ subpackage.short_name }}/index.rst

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx<3
+sphinx<4
 recommonmark==0.6.0
 sphinxcontrib-svg2pdfconverter==0.1.0
 astroid

shared-bindings/_bleio/Adapter.c

@@ -145,8 +145,8 @@ const mp_obj_property_t bleio_adapter_name_obj = {
 //|         .. note: If you set ``anonymous=True``, then a timeout must be specified. If no timeout is
 //|            specified, then the maximum allowed timeout will be selected automatically.
 //|
-//|         :param buf data: advertising data packet bytes
-//|         :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
+//|         :param ~_typing.ReadableBuffer data: advertising data packet bytes
+//|         :param ~_typing.ReadableBuffer scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
 //|         :param bool connectable:  If `True` then other devices are allowed to connect to this peripheral.
 //|         :param bool anonymous:  If `True` then this device's MAC address is randomized before advertising.
 //|         :param int timeout:  If set, we will only advertise for this many seconds.
@@ -219,7 +219,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_advertising_obj, bleio_adapt
 //|         """Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are
 //|         filtered and returned separately.
 //|
-//|         :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets
+//|         :param ~_typing.ReadableBuffer prefixes: Sequence of byte string prefixes to filter advertising packets
 //|             with. A packet without an advertising structure that matches one of the prefixes is
 //|             ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated.
 //|         :param int buffer_size: the maximum number of advertising bytes to buffer.
@@ -334,7 +334,7 @@ const mp_obj_property_t bleio_adapter_connected_obj = {
                (mp_obj_t)&mp_const_none_obj },
 };
 
-//|     connections: tuple
+//|     connections: Tuple[Connection]
 //|     """Tuple of active connections including those initiated through
 //|     :py:meth:`_bleio.Adapter.connect`. (read-only)"""
 //|

shared-bindings/_bleio/Address.c

@@ -42,7 +42,7 @@
 //|         """Create a new Address object encapsulating the address value.
 //|         The value itself can be one of:
 //|
-//|         :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
+//|         :param ~_typing.ReadableBuffer address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
 //|         :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`,
 //|           `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`."""
 //|         ...
@@ -128,7 +128,7 @@ const mp_obj_property_t bleio_address_type_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|     def __eq__(self, other: Address) -> bool:
+//|     def __eq__(self, other: object) -> bool:
 //|         """Two Address objects are equal if their addresses and address types are equal."""
 //|         ...
 //|

shared-bindings/_bleio/Characteristic.c

@@ -63,7 +63,7 @@
 //|          is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum
 //|          number of data bytes that fit in a single BLE 4.x ATT packet.
 //|         :param bool fixed_length: True if the characteristic value is of fixed length.
-//|         :param buf initial_value: The initial value for this characteristic. If not given, will be
+//|         :param ~_typing.ReadableBuffer initial_value: The initial value for this characteristic. If not given, will be
 //|          filled with zeros.
 //|
 //|         :return: the new Characteristic."""

shared-bindings/_bleio/Connection.c

@@ -111,12 +111,12 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection
 
 //|     def discover_remote_services(self, service_uuids_whitelist: Optional[Iterable[UUID]] = None) -> Tuple[Service, ...]:
 //|         """Do BLE discovery for all services or for the given service UUIDS,
-//|          to find their handles and characteristics, and return the discovered services.
-//|          `Connection.connected` must be True.
+//|         to find their handles and characteristics, and return the discovered services.
+//|         `Connection.connected` must be True.
 //|
 //|         :param iterable service_uuids_whitelist:
 //|
-//|           an iterable of :py:class:~`UUID` objects for the services provided by the peripheral
+//|           an iterable of :py:class:`UUID` objects for the services provided by the peripheral
 //|           that you want to use.
 //|
 //|           The peripheral may provide more services, but services not listed are ignored
@@ -126,7 +126,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection
 //|           slow.
 //|
 //|           If the service UUID is 128-bit, or its characteristic UUID's are 128-bit, you
-//|           you must have already created a :py:class:~`UUID` object for that UUID in order for the
+//|           you must have already created a :py:class:`UUID` object for that UUID in order for the
 //|           service or characteristic to be discovered. Creating the UUID causes the UUID to be
 //|           registered for use. (This restriction may be lifted in the future.)
 //|

shared-bindings/_bleio/Descriptor.c

@@ -46,7 +46,7 @@
 //|         as part of remote Characteristics in the remote Services that are discovered."""
 //|
 //|     @classmethod
-//|     def add_to_characteristic(characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length = 20, fixed_length: bool = False, initial_value: ReadableBuffer = b'') -> Descriptor:
+//|     def add_to_characteristic(cls, characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: ReadableBuffer = b'') -> Descriptor:
 //|         """Create a new Descriptor object, and add it to this Service.
 //|
 //|         :param Characteristic characteristic: The characteristic that will hold this descriptor
@@ -61,7 +61,7 @@
 //|            is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum
 //|            number of data bytes that fit in a single BLE 4.x ATT packet.
 //|         :param bool fixed_length: True if the descriptor value is of fixed length.
-//|         :param buf initial_value: The initial value for this descriptor.
+//|         :param ~_typing.ReadableBuffer initial_value: The initial value for this descriptor.
 //|
 //|         :return: the new Descriptor."""
 //|         ...

shared-bindings/_bleio/UUID.c

@@ -48,7 +48,7 @@
 //|         temporary 16-bit UUID that can be used in place of the full 128-bit UUID.
 //|
 //|         :param value: The uuid value to encapsulate
-//|         :type value: int or typing.ByteString"""
+//|         :type value: int, ~_typing.ReadableBuffer or str"""
 //|         ...
 //|
 STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -248,7 +248,7 @@ STATIC mp_obj_t bleio_uuid_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     }
 }
 
-//|     def __eq__(self, other: UUID) -> bool:
+//|     def __eq__(self, other: object) -> bool:
 //|         """Two UUID objects are equal if their values match and they are both 128-bit or both 16-bit."""
 //|         ...
 //|

shared-bindings/_bleio/__init__.c

@@ -41,7 +41,8 @@
 #include "shared-bindings/_bleio/Service.h"
 #include "shared-bindings/_bleio/UUID.h"
 
-//| """
+//| """Bluetooth Low Energy (BLE) communication
+//|
 //| The `_bleio` module provides necessary low-level functionality for communicating
 //| using Bluetooth Low Energy (BLE). The '_' prefix indicates this module is meant
 //| for internal use by libraries but not by the end user. Its API may change incompatibly
@@ -50,12 +51,12 @@
 //| `adafruit_ble <https://circuitpython.readthedocs.io/projects/ble/en/latest/>`_
 //| CircuitPython library instead, which builds on `_bleio`, and
 //| provides higher-level convenience functionality, including predefined beacons, clients,
-//| servers.
-//|
-//| .. attribute:: adapter
+//| servers."""
 //|
-//|   BLE Adapter used to manage device discovery and connections.
-//|   This object is the sole instance of `_bleio.Adapter`."""
+
+//| adapter: Adapter
+//| """BLE Adapter used to manage device discovery and connections.
+//| This object is the sole instance of `_bleio.Adapter`."""
 //|
 
 //| class BluetoothError(Exception):