Document method parameters and use sphinx-autodoc-typehints in docs

Author: phw

discid/disc.py

@@ -37,7 +37,7 @@ def read(
     """Reads the TOC from the device given as string
     and returns a :class:`Disc` object.
 
-    That string can be either of :obj:`str <python:str>` or :obj:`bytes`.
+    The device string can be either of :obj:`str <python:str>` or :obj:`bytes`.
     However, it should in no case contain non-ASCII characters.
     If no device is given, a default, also given by :func:`get_default_device`
     is used.
@@ -50,6 +50,9 @@ def read(
     A :exc:`DiscError` exception is raised when the reading fails,
     and :exc:`NotImplementedError` when libdiscid doesn't support
     reading discs on the current platform.
+
+    :param device: the device name to use or :obj:`None` for using the default device
+    :param features: list of features to enable ("read" will always be assumed)
     """
     disc = Disc()
     disc.read(device, features)
@@ -60,17 +63,18 @@ def put(first: int, last: int, disc_sectors: int, track_offsets: list[int]) -> "
     """Creates a TOC based on the information given
     and returns a :class:`Disc` object.
 
-    Takes the `first` track and `last` **audio** track as :obj:`int`.
-    `disc_sectors` is the end of the last audio track,
-    normally the total sector count of the disc.
-    `track_offsets` is a list of all audio track offsets.
-
     Depending on how you get the total sector count,
     you might have to subtract 11400 (2:32 min.) for discs with data tracks.
 
     A :exc:`TOCError` exception is raised when illegal parameters
     are provided.
 
+    :param first: number of the first audio track
+    :param last: number of the last audio track
+    :param disc_sectors: the end of the last audio track, normally the total
+                         sector count of the disc
+    :param track_offsets: list of all audio track offsets
+
     .. seealso:: :musicbrainz:`Disc ID Calculation`
     """
     disc = Disc()

discid/track.py

@@ -28,7 +28,11 @@
 
 
 class Track(object):
-    """Track objects are part of the :class:`Disc` class."""
+    """Track objects are part of the :class:`Disc` class.
+
+    :param disc: the :class:`Disc` object
+    :param number: the track number
+    """
 
     def __init__(self, disc: "Disc", number: int):
         self._disc = disc
@@ -98,7 +102,7 @@ def seconds(self) -> int:
     def isrc(self) -> str | None:
         """The International Standard Recording Code
 
-        This will be `None` when the `"isrc"` feature was not requested
+        This will be :obj:`None` when the `"isrc"` feature was not requested
         or not supported, otherwise this is a :obj:`str <python:str>` object.
         """
         return self._get_track_isrc()

doc/conf.py

@@ -27,13 +27,15 @@ def __getattr__(cls, name):
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
 ]
 source_suffix = ".rst"
 master_doc = "index"
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", ".venv"]
 
 # General information about the project.
 project = "python-discid"

pyproject.toml

@@ -33,8 +33,9 @@ Changelog = "https://github.com/metabrainz/python-discid/blob/master/CHANGES.rst
 [dependency-groups]
 test = ["pytest"]
 docs = [
-  "Sphinx~=8.1.3",
-  "sphinx-rtd-theme~=3.0.2",
+  "Sphinx>=8.1.3",
+  "sphinx-autodoc-typehints>=3.0.1",
+  "sphinx-rtd-theme>=3.0.2",
 ]
 dev = [
     "pre-commit>=4.5.1",