From d16e25d08053e9df44ec85605e4d7266dc8fda7d Mon Sep 17 00:00:00 2001
From: Christian Rotondo <chris.rotondo6@gmail.com>
Date: Tue, 18 Jun 2024 23:47:23 -0400
Subject: [PATCH 1/2] Add Docstring to functions and class within announce.py
 and contributors.py

---
 doc/sphinxext/announce.py     | 73 +++++++++++++++++++++++++++++++++++
 doc/sphinxext/contributors.py | 24 ++++++++++++
 2 files changed, 97 insertions(+)

diff --git a/doc/sphinxext/announce.py b/doc/sphinxext/announce.py
index 66e999e251c5e..e6b401ea7bca8 100755
--- a/doc/sphinxext/announce.py
+++ b/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)
diff --git a/doc/sphinxext/contributors.py b/doc/sphinxext/contributors.py
index 06f205b5cc3ce..8fb0aca7ab35a 100644
--- a/doc/sphinxext/contributors.py
+++ b/doc/sphinxext/contributors.py
@@ -22,10 +22,21 @@
 
 
 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 +64,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}

From 279a491f2db3ff98d564dd407d43f320386d6b1a Mon Sep 17 00:00:00 2001
From: Christian Rotondo <chris.rotondo6@gmail.com>
Date: Wed, 19 Jun 2024 00:00:32 -0400
Subject: [PATCH 2/2] Apply ruff formatting

---
 doc/sphinxext/contributors.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/sphinxext/contributors.py b/doc/sphinxext/contributors.py
index 8fb0aca7ab35a..24fee9e6047fc 100644
--- a/doc/sphinxext/contributors.py
+++ b/doc/sphinxext/contributors.py
@@ -25,6 +25,7 @@ class ContributorsDirective(Directive):
     """
     Directive to list contributors to a release.
     """
+
     required_arguments = 1
     name = "contributors"