Merge pull request #9 from koenvervloesem/fix_docstrings

Fix docstrings for correct rendering by Sphinx

.pre-commit-config.yaml

@@ -62,8 +62,12 @@ repos:
   hooks:
   - id: flake8
     args: ['--ignore=E501']
-  ## You can add flake8 plugins via `additional_dependencies`:
-  #  additional_dependencies: [flake8-bugbear]
+    additional_dependencies:
+    - flake8-bugbear
+    - flake8-docstrings
+    - flake8-rst
+    - flake8-rst-docstrings
+    - pep8-naming
 
 - repo: https://github.com/pycqa/pylint
   rev: v2.15.9

scripts/generate_modules.py

@@ -22,7 +22,7 @@
 def generate_uuid16_dictionary(kind: str) -> Dict[int, str]:
     """Generate 16-bit UUID dictionary for a module.
 
-    The parameter :param:`kind` should be "sdo_service".
+    The parameter `kind` should be "sdo_service".
 
     Returns a dict with uuid16 keys and their name.
     """
@@ -41,7 +41,7 @@ def generate_uuid16_dictionary(kind: str) -> Dict[int, str]:
 def generate_uuid_dictionaries(kind: str) -> Tuple[Dict[int, str], Dict[str, str]]:
     """Generate UUID dictionaries for a module.
 
-    The parameter :param:`kind` should be "service", "characteristic", or "descriptor".
+    The parameter `kind` should be "service", "characteristic", or "descriptor".
 
     Returns a tuple of dicts with uuid16 and uuid128 keys and their name.
     """
@@ -66,7 +66,7 @@ def generate_uuid_module(
 ) -> None:
     """Generate Python module for UUIDs.
 
-    The parameter :param:`kind` should be "service", "characteristic", or "descriptor".
+    The parameter `kind` should be "service", "characteristic", or "descriptor".
     """
     template = env.get_template(UUID_TEMPLATE)
     with (Path(CODE_DIR) / f"_{kind}s.py").open("w") as python_file:

setup.cfg

@@ -115,9 +115,25 @@ formats = bdist_wheel
 [flake8]
 # Some sane defaults for the code style checker flake8
 max_line_length = 88
+# flake8-docstrings config
+docstring-convention = google
+# For flake8-rst-docstrings:
+rst-roles =
+    class,
+    func,
+    ref,
+rst-directives =
+    envvar,
+    exception,
+rst-substitutions =
+    version,
 extend_ignore = E203, W503
 # ^  Black-compatible
 #    E203 and W503 have edge cases handled by black
+    RST307,
+    # Google Python style is not RST until after processed by Napoleon
+    # See https://github.com/peterjc/flake8-rst-docstrings/issues/17
+    RST201,RST203,RST301,
 exclude =
     .tox
     build

setup.py

@@ -1,10 +1,10 @@
-"""
-    Setup file for bluetooth-numbers.
-    Use setup.cfg to configure your project.
+"""Setup file for bluetooth-numbers.
+
+Use setup.cfg to configure your project.
 
-    This file was generated with PyScaffold 4.3.1.
-    PyScaffold helps you to put up the scaffold of your new Python project.
-    Learn more under: https://pyscaffold.org/
+This file was generated with PyScaffold 4.3.1.
+PyScaffold helps you to put up the scaffold of your new Python project.
+Learn more under: https://pyscaffold.org/
 """
 from setuptools import setup
 

src/bluetooth_numbers/__init__.py

@@ -1,10 +1,8 @@
 # pylint: skip-file
-"""bluetooth-numbers
+"""bluetooth-numbers: Python package with a wide set of numbers related to Bluetooth.
 
-Python package with a wide set of numbers related to Bluetooth
-
-This project offers a Python package with a wide set of numbers related to Bluetooth,
-so Python projects can easily use these numbers.
+This project offers a Python package with company IDs, service, characteristic and
+descriptor UUIDs and OUIs, so Python projects can easily use these numbers.
 
 Get the description of a company ID:
 

src/bluetooth_numbers/dicts.py

@@ -1,6 +1,4 @@
-"""Module with specialized dictionary classes for UUIDs, CICs and OUIs used in
-Bluetooth applications.
-"""
+"""Module with specialized dictionary classes for UUIDs, CICs and OUIs."""
 from typing import Dict, Union
 from uuid import UUID
 
@@ -24,25 +22,25 @@ class CICDict(Dict[int, str]):
 
     You can use this class as a dict with the following differences:
 
-    - If you check for a key that doesn't exist, this raises an UnknownCICError.
+    - If you check for a key that doesn't exist, this raises an
+      :class:`~bluetooth_numbers.exceptions.UnknownCICError`.
     - If you check for a key that isn't a 16-bit unsigned integer, this raises a
-      No16BitIntegerError.
-
-    Example:
-
-    >>> from bluetooth_numbers import company
-    >>> company[0x004C]
-    'Apple, Inc.'
-    >>> company[-1]
-    Traceback (most recent call last):
-    bluetooth_numbers.exceptions.No16BitIntegerError: -1
-    >>> company[65534]
-    Traceback (most recent call last):
-    bluetooth_numbers.exceptions.UnknownCICError: 65534
+      :class:`~bluetooth_numbers.exceptions.No16BitIntegerError`.
+
+    Examples:
+        >>> from bluetooth_numbers import company
+        >>> company[0x004C]
+        'Apple, Inc.'
+        >>> company[-1]
+        Traceback (most recent call last):
+        bluetooth_numbers.exceptions.No16BitIntegerError: -1
+        >>> company[65534]
+        Traceback (most recent call last):
+        bluetooth_numbers.exceptions.UnknownCICError: 65534
     """
 
     def __missing__(self, key: int) -> str:
-        """Try the key and raise exception when it's invalid"""
+        """Try the key and raise exception when it's invalid."""
         if is_uint16(key):
             raise UnknownCICError(key)
 
@@ -56,66 +54,65 @@ class OUIDict(Dict[str, str]):
 
     - You can check for an OUI in the formats "xx:yy:zz", "xx-yy-zz" or "xxyyzz".
       Both lowercase and uppercase letters are supported.
-    - If you check for a key that doesn't exist, this raises an UnknownOUIError.
+    - If you check for a key that doesn't exist, this raises an
+      :class:`~bluetooth_numbers.exceptions.UnknownOUIError`.
     - If you check for a key that doesn't have one of the supported formats, this
-      raises WrongOUIFormatError.
-
-    Example:
-
-    >>> from bluetooth_numbers import oui
-    >>> oui["98:E7:43"]
-    'Dell Inc.'
-    >>> oui["c4-29-96"]
-    'Signify B.V.'
-    >>> oui["A44519"]
-    'Xiaomi Communications Co Ltd'
-    >>> oui["FOOBAR"]
-    Traceback (most recent call last):
-    bluetooth_numbers.exceptions.WrongOUIFormatError: 'FOOBAR'
-    >>> oui["AB:CD:EF"]
-    Traceback (most recent call last):
-    bluetooth_numbers.exceptions.UnknownOUIError: AB:CD:EF
+      raises a :class:`~bluetooth_numbers.exceptions.WrongOUIFormatError`.
+
+    Examples:
+        >>> from bluetooth_numbers import oui
+        >>> oui["98:E7:43"]
+        'Dell Inc.'
+        >>> oui["c4-29-96"]
+        'Signify B.V.'
+        >>> oui["A44519"]
+        'Xiaomi Communications Co Ltd'
+        >>> oui["FOOBAR"]
+        Traceback (most recent call last):
+        bluetooth_numbers.exceptions.WrongOUIFormatError: 'FOOBAR'
+        >>> oui["AB:CD:EF"]
+        Traceback (most recent call last):
+        bluetooth_numbers.exceptions.UnknownOUIError: AB:CD:EF
     """
 
     def __missing__(self, key: str) -> str:
-        """Try the key and raise exception when it's invalid"""
+        """Try the key and raise exception when it's invalid."""
         if is_normalized_oui(key):
             raise UnknownOUIError(key)
 
         return self[normalize_oui(key)]
 
 
 class UUIDDict(Dict[Union[UUID, int], str]):
-    """Dictionary class that converts 128-bit standard UUID keys to 16-bit when the key
-    is missing.
+    """Dictionary class to hold 16-bit and 128-bit standard UUID keys and descriptions.
 
     You can use this class as a dict for Bluetooth UUIDs, with the following
     differences:
 
     - If you check for a 128-bit standard UUID and this UUID doesn't exist in the
       dictionary, it will check for the corresponding 16-bit UUID.
-    - If you check for a UUID that doesn't exist, this raises an UnknownUUIDError.
+    - If you check for a UUID that doesn't exist, this raises an
+      :class:`~bluetooth_numbers.exceptions.UnknownUUIDError`.
     - If you check for a key that isn't a 16-bit unsigned integer, this raises a
-      No16BitIntegerError.
-
-    Example:
-
-    >>> from bluetooth_numbers import service
-    >>> from uuid import UUID
-    >>> service[UUID("0000180F-0000-1000-8000-00805F9B34FB")]
-    'Battery Service'
-    >>> service[0x180F]
-    'Battery Service'
-    >>> service[0]
-    Traceback (most recent call last):
-    bluetooth_numbers.exceptions.UnknownUUIDError: 0
-    >>> service[6.5]
-    Traceback (most recent call last):
-    bluetooth_numbers.exceptions.No16BitIntegerError: 6.5
+      :class:`~bluetooth_numbers.exceptions.No16BitIntegerError`.
+
+    Examples:
+        >>> from bluetooth_numbers import service
+        >>> from uuid import UUID
+        >>> service[UUID("0000180F-0000-1000-8000-00805F9B34FB")]
+        'Battery Service'
+        >>> service[0x180F]
+        'Battery Service'
+        >>> service[0]
+        Traceback (most recent call last):
+        bluetooth_numbers.exceptions.UnknownUUIDError: 0
+        >>> service[6.5]
+        Traceback (most recent call last):
+        bluetooth_numbers.exceptions.No16BitIntegerError: 6.5
     """
 
     def __missing__(self, key: Union[UUID, int]) -> str:
-        """Try the key converted to 16-bit UUID"""
+        """Try the key converted to 16-bit UUID."""
         if isinstance(key, UUID):
             try:
                 uuid16_key = uuid128_to_uuid16(key)