Add Types to Docstrings: chango and chango.abc

docs/source/conf.py

@@ -115,4 +115,3 @@ def missing_reference(
 
 def setup(app: Sphinx) -> None:
     app.connect("missing-reference", missing_reference)
-    # app.connect("autodoc-process-bases", autodoc_process_bases)

src/chango/__init__.py

@@ -18,4 +18,4 @@
 from ._version import Version
 
 #: :obj:`str`: The version of the ``chango`` library as string
-__version__ = __about__.__version__
+__version__: str = __about__.__version__

src/chango/_changenoteinfo.py

@@ -12,18 +12,18 @@ class ChangeNoteInfo:
     """Objects of this type represents metadata about a change note.
 
     Args:
-        uid: Unique identifier of this change note.
-        version: The version the change note belongs to. May be :obj:`None` if the change note is
-            not yet released.
-        path: The file path this change note is stored at.
+        uid (:obj:`str`): Unique identifier of this change note.
+        version (:class:`~chango.Version` | :obj:`None`): The version the change note belongs to.
+            May be :obj:`None` if the change note is not yet released.
+        file_path (:class:`pathlib.Path`): The file path this change note is stored at.
 
     Attributes:
-        uid: Unique identifier of this change note.
-        version: The version the change note belongs to. May be :obj:`None` if the change note is
-            not yet released.
-        path: The file path this change note is stored at.
+        uid (:obj:`str`): Unique identifier of this change note.
+        version (:class:`~chango.Version` | :obj:`None`): The version the change note belongs to.
+            May be :obj:`None` if the change note is not yet released.
+        file_path (:class:`pathlib.Path`): The file path this change note is stored at.
     """
 
     uid: str
     version: Version | None
-    path: Path
+    file_path: Path

src/chango/_cli/edit.py

@@ -20,4 +20,4 @@ def edit(
     ],
 ) -> None:
     """Edit an existing change note in the default editor."""
-    typer.launch(get_chango_instance().scanner.lookup_change_note(uid).path.as_posix())
+    typer.launch(get_chango_instance().scanner.lookup_change_note(uid).file_path.as_posix())

src/chango/_version.py

@@ -10,12 +10,12 @@ class Version:
     """Objects of this type represent a released version of a software project.
 
     Args:
-        uid: Unique identifier / version number of this version.
-        date: Release date of this version.
+        uid (:obj:`str`): Unique identifier / version number of this version.
+        date (:class:`datetime.date`): Release date of this version.
 
     Attributes:
-        uid: Unique identifier / version number of this version.
-        date: Release date of this version.
+        uid (:obj:`str`): Unique identifier / version number of this version.
+        date (:class:`datetime.date`): Release date of this version.
     """
 
     uid: str

src/chango/abc/_changenote.py

@@ -14,8 +14,8 @@ class ChangeNote(abc.ABC):
     """Abstract base class for a change note describing a single change in a software project.
 
     Args:
-        slug: A short, human-readable identifier for the change note.
-        uid: A unique identifier for the change note. If not provided, a
+        slug (:obj:`str`): A short, human-readable identifier for the change note.
+        uid (:obj:`str`): A unique identifier for the change note. If not provided, a
             random identifier will be generated. Should be 8 characters long and consist of
             lowercase letters and digits.
     """
@@ -25,19 +25,19 @@ def __init__(self, slug: str, uid: str | None = None):
 
     @property
     def slug(self) -> str:
-        """The short, human-readable identifier for the change note."""
+        """:obj:`str`: The short, human-readable identifier for the change note."""
         return self._file_name.slug
 
     @property
     def uid(self) -> str:
-        """The unique identifier for the change note."""
+        """:obj:`str`: The unique identifier for the change note."""
         return self._file_name.uid
 
     @property
     @abc.abstractmethod
     def file_extension(self) -> str:
-        """The file extension to use when writing the change note to a file. The extension must
-        *not* include the leading dot.
+        """:obj:`str`: The file extension to use when writing the change note to a file. The
+        extension must *not* include the leading dot.
         """
 
     @classmethod
@@ -49,8 +49,9 @@ def build_template(cls, slug: str, uid: str | None = None) -> Self:
             This will be used to create a new change note in the CLI.
 
         Args:
-            slug: The slug to use for the change note.
-            uid: The unique identifier for the change note or :obj:`None` to generate a random one.
+            slug (:obj:`str`): The slug to use for the change note.
+            uid (:obj:`str`): The unique identifier for the change note or :obj:`None` to generate
+                a random one.
 
         Returns:
             The :class:`ChangeNote` object.
@@ -70,11 +71,11 @@ def from_file(cls, file_path: PathLike, encoding: str = UTF8) -> Self:
             This convenience method calls :meth:`from_bytes` internally.
 
         Args:
-            file_path: The path to the file to read from.
-            encoding: The encoding to use for reading.
+            file_path (:class:`pathlib.Path` | :obj:`str`): The path to the file to read from.
+            encoding (:obj:`str`): The encoding to use for reading.
 
         Returns:
-            The :class:`ChangeNote` object.
+            :class:`ChangeNote`: The :class:`ChangeNote` object.
 
         Raises:
             :class:`chango.error.ValidationError`: If the data is not a valid change note file.
@@ -95,13 +96,13 @@ def from_bytes(cls, slug: str, uid: str, data: bytes, encoding: str = UTF8) -> S
             This convenience method calls :meth:`from_string` internally.
 
         Args:
-            slug: The slug of the change note.
-            uid: The UID of the change note.
-            data: The bytes to read from.
-            encoding: The encoding to use for reading.
+            slug (:obj:`str`): The slug of the change note.
+            uid (:obj:`str`): The UID of the change note.
+            data (:obj:`bytes`): The bytes to read from.
+            encoding (:obj:`str`): The encoding to use for reading.
 
         Returns:
-            The :class:`ChangeNote` object.
+            :class:`ChangeNote`: The :class:`ChangeNote` object.
 
         Raises:
             :class:`chango.error.ValidationError`: If the data is not a valid change note file.
@@ -116,12 +117,12 @@ def from_string(cls, slug: str, uid: str, string: str) -> Self:
         :exc:`~chango.error.ValidationError` in that case.
 
         Args:
-            slug: The slug of the change note.
-            uid: The UID of the change note.
-            string: The string to read from.
+            slug (:obj:`str`): The slug of the change note.
+            uid (:obj:`str`): The UID of the change note.
+            string (:obj:`str`): The string to read from.
 
         Returns:
-            The :class:`ChangeNote` object.
+            :class:`ChangeNote`: The :class:`ChangeNote` object.
 
         Raises:
             :class:`chango.error.ValidationError`: If the string is not a valid change note.
@@ -136,10 +137,10 @@ def to_bytes(self, encoding: str = UTF8) -> bytes:
             This convenience method calls :meth:`to_string` internally.
 
         Args:
-            encoding: The encoding to use for writing.
+            encoding (:obj:`str`): The encoding to use for writing.
 
         Returns:
-            The bytes data.
+            :obj:`bytes`: The bytes data.
         """
         return self.to_string().encode(encoding)
 
@@ -149,10 +150,10 @@ def to_string(self, encoding: str = UTF8) -> str:
         and reading back in with :meth:`from_string`.
 
         Args:
-            encoding: The encoding to use for writing.
+            encoding (:obj:`str`): The encoding to use for writing.
 
         Returns:
-            The string data.
+            :obj:`str`: The string data.
         """
 
     def to_file(self, directory: PathLike | None = None, encoding: str = UTF8) -> Path:
@@ -164,7 +165,7 @@ def to_file(self, directory: PathLike | None = None, encoding: str = UTF8) -> Pa
         Args:
             directory: Optional. The directory to write the file to. If not provided, the file
                 will be written to the current working directory.
-            encoding: The encoding to use for writing.
+            encoding (:obj:`str`): The encoding to use for writing.
 
         Returns:
             :class:`pathlib.Path`: The path to the file that was written.

src/chango/abc/_chango.py

@@ -26,7 +26,9 @@ class ChanGo[VST: VersionScanner, VHT: VersionHistory, VNT: VersionNote, CNT: Ch
     @property
     @abc.abstractmethod
     def scanner(self) -> VST:
-        """The used :class:`~chango.abc.VersionScanner`."""
+        """:class:`VST <typing.TypeVar>`: The :class:`~chango.abc.VersionScanner` used by this
+        instance.
+        """
 
     @abc.abstractmethod
     def build_template_change_note(self, slug: str, uid: str | None = None) -> CNT:
@@ -36,32 +38,40 @@ def build_template_change_note(self, slug: str, uid: str | None = None) -> CNT:
             This will be used to create a new change note in the CLI.
 
         Args:
-            slug: The slug to use for the change note.
-            uid: The unique identifier for the change note or :obj:`None` to generate a random one.
+            slug (:obj:`str`): The slug to use for the change note.
+            uid (:obj:`str`, optional): The unique identifier for the change note or :obj:`None`
+                to generate a random one.
 
         Returns:
-            The :class:`~chango.abc.ChangeNote` object.
+            :class:`CNT <typing.TypeVar>`:The :class:`~chango.abc.ChangeNote` object.
         """
 
     @abc.abstractmethod
     def build_version_note(self, version: VUIDInput) -> VNT:
         """Build a new empty version note.
 
         Args:
-            version: The version of the software project this note is for.
-                May be :obj:`None` if the version is not yet released.
+            version (:class:`~chango.Version` | :obj:`str` | :obj:`None`): The version of the
+                software project this note is for. May be :obj:`None` if the version is not yet
+                released.
+
+        Returns:
+            :class:`VNT <typing.TypeVar>`: The :class:`~chango.abc.VersionNote` object.
         """
 
     @abc.abstractmethod
     def build_version_history(self) -> VHT:
-        """Build a new empty version history."""
+        """:class:`VHT <typing.TypeVar>`: Build a new empty version history."""
 
     @abc.abstractmethod
     def load_change_note(self, uid: str) -> CNT:
         """Load a change note with the given identifier.
 
         Args:
-            uid: The unique identifier or file name of the change note to load.
+            uid (:obj:`str`): The unique identifier or file name of the change note to load.
+
+        Returns:
+            :class:`CNT <typing.TypeVar>`: The :class:`~chango.abc.ChangeNote` object.
         """
 
     @abc.abstractmethod
@@ -74,9 +84,13 @@ def get_write_directory(self, change_note: CNT | str, version: VUIDInput) -> Pat
               expected that :paramref:`version` is of type :class:`~chango.Version`.
 
         Args:
-            change_note: The change note to write or its UID.
-            version: The version the change note belongs to. Maybe be
-                :obj:`None` if the change note is not yet released.
+            change_note (:class:`CNT <typing.TypeVar>` | :obj:`str`): The change note to write or
+                its UID.
+            version (:class:`~chango.Version` | :obj:`str` | :obj:`None`): The version the change
+                note belongs to. Maybe be :obj:`None` if the change note is not yet released.
+
+        Returns:
+            :class:`pathlib.Path`: The directory to write the change note to.
         """
 
     def write_change_note(
@@ -85,13 +99,13 @@ def write_change_note(
         """Write a change note to disk.
 
         Args:
-            change_note: The change note to write.
-            version: The version the change note belongs to. Maybe be
-                :obj:`None` if the change note is not yet released.
-            encoding: The encoding to use for writing.
+            change_note (:class:`CNT <typing.TypeVar>` | :obj:`str`): The change note to write.
+            version (:class:`~chango.Version` | :obj:`str` | :obj:`None`): The version the change
+                note belongs to. Maybe be :obj:`None` if the change note is not yet released.
+            encoding (:obj:`str`): The encoding to use for writing.
 
         Returns:
-            The file path the change note was written to.
+            :class:`pathlib.Path`: The file path the change note was written to.
         """
         return change_note.to_file(
             self.get_write_directory(change_note=change_note, version=version), encoding=encoding
@@ -101,8 +115,11 @@ def load_version_note(self, version: VUIDInput) -> VNT:
         """Load a version note.
 
         Args:
-            version: The version of the version note to load. May be :obj:`None` if the version is
-                not yet released.
+            version (:class:`~chango.Version` | :obj:`str` | :obj:`None`): The version of the
+                version note to load. May be :obj:`None` if the version is not yet released.
+
+        Returns:
+            :class:`VNT <typing.TypeVar>`: The loaded :class:`~chango.abc.VersionNote`.
         """
         changes = self.scanner.get_changes(version)
         version_note = self.build_version_note(version=version)
@@ -115,16 +132,18 @@ def load_version_history(self, start_from: VUIDInput = None, end_at: VUIDInput =
         """Load the version history.
 
         Important:
-            Unreleased changes are included in the returned version history, if available.
+            By default, unreleased changes are included in the returned version history, if
+            available.
 
         Args:
-            start_from: The version to start from. If :obj:`None`, start from the
-                earliest available version.
-            end_at: The version to end at. If :obj:`None`, end at the latest available
-                version, *including* unreleased changes.
+            start_from (:class:`~chango.Version` | :obj:`str`, optional): The version to start
+                from. If :obj:`None`, start from the earliest available version.
+            end_at (:class:`~chango.Version` | :obj:`str`, optional): The version to end at.
+                If :obj:`None`, end at the latest available version, *including* unreleased
+                changes.
 
         Returns:
-            The loaded version history.
+            :class:`VHT <typing.TypeVar>`: The loaded version :class:`~chango.abc.VersionHistory`.
         """
         version_history = self.build_version_history()
 
@@ -142,18 +161,18 @@ def release(self, version: "Version") -> bool:
         if necessary.
 
         Args:
-            version: The version to release.
+            version (:class:`~chango.Version`): The version to release.
 
         Returns:
-            Whether a release was performed. If no unreleased changes are available, this method
-            returns :obj:`False`.
+            :obj:`bool`: Whether a release was performed. If no unreleased changes are available,
+            this method returns :obj:`False`.
         """
         if not self.scanner.has_unreleased_changes():
             return False
         for uid in self.scanner.get_changes(None):
             change_info = self.scanner.lookup_change_note(uid)
             write_dir = self.get_write_directory(uid, version)
-            if change_info.path.parent != write_dir:
-                change_info.path.rename(write_dir / change_info.path.name)
+            if change_info.file_path.parent != write_dir:
+                change_info.file_path.rename(write_dir / change_info.file_path.name)
 
         return True

src/chango/abc/_versionhistory.py

@@ -48,15 +48,17 @@ def add_version_note(self, version_note: VNT) -> None:
         """Add a version note to the version note.
 
         Args:
-            version_note: The version note to add.
+            version_note (:class:`VNT <typing.TypeVar>`): The :class:`~chango.abc.VersionNote`
+                note to add.
         """
         self[version_note.uid] = version_note  # type: ignore[index]
 
     def remove_version_note(self, version_note: VNT) -> None:
         """Remove a version note from the version note.
 
         Args:
-            version_note: The version note to remove.
+            version_note (:class:`VNT <typing.TypeVar>`): The :class:`~chango.abc.VersionNote`
+                note to remove.
         """
         del self[version_note.uid]  # type: ignore[arg-type]
 
@@ -73,7 +75,7 @@ def render(self, markup: str) -> str:
               :attr:`~chango.abc.VersionNote.date` if available.
 
         Args:
-            markup: The markup language to use for rendering. If the markup language
+            markup (:obj:`str`): The markup language to use for rendering. If the markup language
                 is not supported, an :exc:`~chango.error.UnsupportedMarkupError` should be raised.
 
         Returns: