From c48aa1037c0be3e000db72f640700bfa9de1d22b Mon Sep 17 00:00:00 2001 From: malhar2460 Date: Sat, 25 May 2024 14:46:14 +0530 Subject: [PATCH 1/2] Added doc string to announce.py and contibutors.py --- doc/sphinxext/announce.py | 131 ++++++++++++++++++++++++++++++++++ doc/sphinxext/contributors.py | 43 +++++++++++ 2 files changed, 174 insertions(+) diff --git a/doc/sphinxext/announce.py b/doc/sphinxext/announce.py index 66e999e251c5e..b6f57c0cdea87 100755 --- a/doc/sphinxext/announce.py +++ b/doc/sphinxext/announce.py @@ -57,6 +57,34 @@ def get_authors(revision_range): + """ + Extract authors from a range of revisions + + This designed to list the authors who contributed to a given range of revisions in a Git repository. + It identifies new contributors within range and distinguishes them with a "+" sign. + + Parameters + ---------- + revision_range : str + Release dates. + + Returns + ------- + List + List of authors. + + Examples + ------- + >>> authors = get_authors("v1.0.0..v1.1.0") + >>> print(authors) + ['Alice +', 'Bob', 'Charlie +'] + + Either between these ranges or latest commit. + + >>> authors = get_authors("v1.0.0..v1.1.0|HEAD") + >>> print(authors) + ['Alice +', 'Bob', 'Charlie +', 'Dave +'] + """ pat = "^.*\\t(.*)$" lst_release, cur_release = (r.strip() for r in revision_range.split("..")) @@ -109,6 +137,31 @@ def get_authors(revision_range): def get_pull_requests(repo, revision_range): + """ + Extract pull request numbers from a range of revisions + + This function identifies pull requests merged in a given range of revisions + in a Git repository. It includes regular merges, auto merges, and squash-merges. + + Parameters + ---------- + repo : github.Repository.Repository + The GitHub repository object. + revision_range : str + The range of revisions to examine, in the format "..". + + Returns + ------- + List + List of pull requests. + + Examples + -------- + >>> repo = github.Github("").get_repo("/") + >>> prs = get_pull_requests(repo, "v1.0.0..v1.1.0") + >>> print([pr.number for pr in prs]) + [123, 124, 125] + """ prnums = [] # From regular merges @@ -134,6 +187,34 @@ def get_pull_requests(repo, revision_range): def build_components(revision_range, heading="Contributors"): + """ + Build components for the release notes + + This function constructs the components required for generating the release notes, + including the heading, author message, and list of authors. + + Parameters + ---------- + revision_range : str + The range of revisions to examine, in the format "..". + heading : str, optional + The heading for the release notes, by default "Contributors". + + Returns + ------- + dict + Dictionary containing the heading, author message, and list of authors. + + Examples + -------- + >>> components = build_components("v1.0.0..v1.1.0") + >>> print(components["heading"]) + Contributors + >>> print(components["author_message"]) + A total of 3 people contributed patches to this release. People with a "+" by their names contributed a patch for the first time. + >>> print(components["authors"]) + ['Alice +', 'Bob', 'Charlie +'] + """ lst_release, cur_release = (r.strip() for r in revision_range.split("..")) authors = get_authors(revision_range) @@ -145,6 +226,35 @@ def build_components(revision_range, heading="Contributors"): def build_string(revision_range, heading="Contributors"): + """ + Build the release notes string + + This function formats the release notes as a string using the components generated + by build_components. + + Parameters + ---------- + revision_range : str + The range of revisions to examine, in the format "..". + heading : str, optional + The heading for the release notes, by default "Contributors". + + Returns + ------- + str + Formatted release notes. + + Examples + -------- + >>> release_notes = build_string("v1.0.0..v1.1.0") + >>> print(release_notes) + Contributors + ============ + A total of 3 people contributed patches to this release. People with a "+" by their names contributed a patch for the first time. + * Alice + + * Bob + * Charlie + + """ components = build_components(revision_range, heading=heading) components["uline"] = "=" * len(components["heading"]) components["authors"] = "* " + "\n* ".join(components["authors"]) @@ -162,6 +272,27 @@ def build_string(revision_range, heading="Contributors"): def main(revision_range): + """ + Main function to generate and print the release notes + + This function generates the release notes for the given revision range + and prints them to the standard output. + + Parameters + ---------- + revision_range : str + The range of revisions to examine, in the format "..". + + Examples + -------- + >>> main("v1.0.0..v1.1.0") + Contributors + ============ + A total of 3 people contributed patches to this release. People with a "+" by their names contributed a patch for the first time. + * Alice + + * Bob + * Charlie + + """ # document authors text = build_string(revision_range) print(text) diff --git a/doc/sphinxext/contributors.py b/doc/sphinxext/contributors.py index 06f205b5cc3ce..3aad143defda3 100644 --- a/doc/sphinxext/contributors.py +++ b/doc/sphinxext/contributors.py @@ -26,6 +26,26 @@ class ContributorsDirective(Directive): name = "contributors" def run(self): + """ + Execute the ContributorsDirective directive. + + This function retrieves information about code contributors and commits within + a specified version range and generates a list of contributors to include in the + documentation. + + Returns + ------- + List + List containing author message and contributors. + + Examples + -------- + >>> directive = ContributorsDirective() + >>> directive.arguments = ['v0.23.0..v0.23.1'] + >>> nodes = directive.run() + >>> nodes + [, ] + """ range_ = self.arguments[0] if range_.endswith("x..HEAD"): return [nodes.paragraph(), nodes.bullet_list()] @@ -53,6 +73,29 @@ def run(self): def setup(app): + """ + Setup function for the Sphinx extension. + + This function initializes the Sphinx extension, adding the 'contributors' directive + to the app. + + Parameters + ---------- + app : sphinx.application.Sphinx + The Sphinx application object. + + Returns + ------- + dict + A dictionary containing version information and safety flags for the extension. + + Examples + -------- + >>> app = App() + >>> setup_info = setup(app) + >>> setup_info + {'version': '0.1', 'parallel_read_safe': True, 'parallel_write_safe': True} + """ app.add_directive("contributors", ContributorsDirective) return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True} From 8c8a858da14b4d7eab11d13abd0114012d6b2f86 Mon Sep 17 00:00:00 2001 From: malhar2460 Date: Tue, 28 May 2024 19:01:01 +0530 Subject: [PATCH 2/2] Removed examples from the doc string --- doc/sphinxext/announce.py | 52 +---------------------------------- doc/sphinxext/contributors.py | 15 ---------- 2 files changed, 1 insertion(+), 66 deletions(-) diff --git a/doc/sphinxext/announce.py b/doc/sphinxext/announce.py index b6f57c0cdea87..18a028248775e 100755 --- a/doc/sphinxext/announce.py +++ b/doc/sphinxext/announce.py @@ -58,7 +58,7 @@ def get_authors(revision_range): """ - Extract authors from a range of revisions + Extract authors from a range of revisions. This designed to list the authors who contributed to a given range of revisions in a Git repository. It identifies new contributors within range and distinguishes them with a "+" sign. @@ -72,18 +72,6 @@ def get_authors(revision_range): ------- List List of authors. - - Examples - ------- - >>> authors = get_authors("v1.0.0..v1.1.0") - >>> print(authors) - ['Alice +', 'Bob', 'Charlie +'] - - Either between these ranges or latest commit. - - >>> authors = get_authors("v1.0.0..v1.1.0|HEAD") - >>> print(authors) - ['Alice +', 'Bob', 'Charlie +', 'Dave +'] """ pat = "^.*\\t(.*)$" lst_release, cur_release = (r.strip() for r in revision_range.split("..")) @@ -154,13 +142,6 @@ def get_pull_requests(repo, revision_range): ------- List List of pull requests. - - Examples - -------- - >>> repo = github.Github("").get_repo("/") - >>> prs = get_pull_requests(repo, "v1.0.0..v1.1.0") - >>> print([pr.number for pr in prs]) - [123, 124, 125] """ prnums = [] @@ -204,16 +185,6 @@ def build_components(revision_range, heading="Contributors"): ------- dict Dictionary containing the heading, author message, and list of authors. - - Examples - -------- - >>> components = build_components("v1.0.0..v1.1.0") - >>> print(components["heading"]) - Contributors - >>> print(components["author_message"]) - A total of 3 people contributed patches to this release. People with a "+" by their names contributed a patch for the first time. - >>> print(components["authors"]) - ['Alice +', 'Bob', 'Charlie +'] """ lst_release, cur_release = (r.strip() for r in revision_range.split("..")) authors = get_authors(revision_range) @@ -243,17 +214,6 @@ def build_string(revision_range, heading="Contributors"): ------- str Formatted release notes. - - Examples - -------- - >>> release_notes = build_string("v1.0.0..v1.1.0") - >>> print(release_notes) - Contributors - ============ - A total of 3 people contributed patches to this release. People with a "+" by their names contributed a patch for the first time. - * Alice + - * Bob - * Charlie + """ components = build_components(revision_range, heading=heading) components["uline"] = "=" * len(components["heading"]) @@ -282,16 +242,6 @@ def main(revision_range): ---------- revision_range : str The range of revisions to examine, in the format "..". - - Examples - -------- - >>> main("v1.0.0..v1.1.0") - Contributors - ============ - A total of 3 people contributed patches to this release. People with a "+" by their names contributed a patch for the first time. - * Alice + - * Bob - * Charlie + """ # document authors text = build_string(revision_range) diff --git a/doc/sphinxext/contributors.py b/doc/sphinxext/contributors.py index 3aad143defda3..17a5acacf7ec1 100644 --- a/doc/sphinxext/contributors.py +++ b/doc/sphinxext/contributors.py @@ -37,14 +37,6 @@ def run(self): ------- List List containing author message and contributors. - - Examples - -------- - >>> directive = ContributorsDirective() - >>> directive.arguments = ['v0.23.0..v0.23.1'] - >>> nodes = directive.run() - >>> nodes - [, ] """ range_ = self.arguments[0] if range_.endswith("x..HEAD"): @@ -88,13 +80,6 @@ def setup(app): ------- dict A dictionary containing version information and safety flags for the extension. - - Examples - -------- - >>> app = App() - >>> setup_info = setup(app) - >>> setup_info - {'version': '0.1', 'parallel_read_safe': True, 'parallel_write_safe': True} """ app.add_directive("contributors", ContributorsDirective)