Add docstrings to functions, methods, and class in announce.py and contributors.py

doc/sphinxext/announce.py

@@ -57,6 +57,21 @@
 
 
 def get_authors(revision_range):
+    """
+    Finds and returns authors within the revision range.
+
+    Parameters
+    -----------
+    revision_range : str
+        Revision range to search for authors.
+
+    Returns
+    -------
+    list[str]
+        List of authors in the revision range.
+
+
+    """
     pat = "^.*\\t(.*)$"
     lst_release, cur_release = (r.strip() for r in revision_range.split(".."))
 
@@ -109,6 +124,22 @@ def get_authors(revision_range):
 
 
 def get_pull_requests(repo, revision_range):
+    """
+    Finds and returns pull requests within the revision range.
+
+    Parameters
+    -----------
+    repo : github.Repository.Repository
+        GitHub repository object.
+    revision_range : str
+        Revision range to search for pull requests.
+
+    Returns
+    -------
+    list[github.PullRequest.PullRequest]
+        List of pull requests in the revision range.
+    """
+
     prnums = []
 
     # From regular merges
@@ -134,6 +165,21 @@ def get_pull_requests(repo, revision_range):
 
 
 def build_components(revision_range, heading="Contributors"):
+    """
+    Builds components for the release announcement.
+
+    Parameters
+    -----------
+    revision_range : str
+        Revision range to search for authors.
+    heading : str
+        Heading for the announcement.
+
+    Returns
+    -------
+    dict[str, str]
+        Dictionary containing the components for the announcement.
+    """
     lst_release, cur_release = (r.strip() for r in revision_range.split(".."))
     authors = get_authors(revision_range)
 
@@ -145,6 +191,21 @@ def build_components(revision_range, heading="Contributors"):
 
 
 def build_string(revision_range, heading="Contributors"):
+    """
+    Builds a string for the release announcement.
+
+    Parameters
+    -----------
+    revision_range : str
+        Revision range to search for authors.
+    heading : str
+        Heading for the announcement.
+
+    Returns
+    -------
+    str
+        String for the release announcement.
+    """
     components = build_components(revision_range, heading=heading)
     components["uline"] = "=" * len(components["heading"])
     components["authors"] = "* " + "\n* ".join(components["authors"])
@@ -162,6 +223,18 @@ def build_string(revision_range, heading="Contributors"):
 
 
 def main(revision_range):
+    """
+    Main function for generating author lists for release.
+
+    Parameters
+    -----------
+    revision_range : str
+        Revision range to search for authors.
+
+    Returns
+    -------
+    None
+    """
     # document authors
     text = build_string(revision_range)
     print(text)

doc/sphinxext/contributors.py

@@ -22,10 +22,22 @@
 
 
 class ContributorsDirective(Directive):
+    """
+    Directive to list contributors to a release.
+    """
+
     required_arguments = 1
     name = "contributors"
 
     def run(self):
+        """
+        Run the directive.
+
+        Returns
+        -------
+        list[docutils.nodes.Node]
+            List of nodes to include in the document.
+        """
         range_ = self.arguments[0]
         if range_.endswith("x..HEAD"):
             return [nodes.paragraph(), nodes.bullet_list()]
@@ -53,6 +65,19 @@ def run(self):
 
 
 def setup(app):
+    """
+    Set up the extension.
+
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application.
+
+    Returns
+    -------
+    dict
+        Metadata for the extension.
+    """
     app.add_directive("contributors", ContributorsDirective)
 
     return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}