Updated logging scripts

iamwatchdogs · iamwatchdogs · commit 125ed576307d · 2024-10-19T08:40:52.000+05:30
updated scripts to properly log the contributions made to the files
whose parent directory is .github and to make sure the same is reflected
within deployed pages the markdown updation script were modified.
diff --git a/.github/scripts/convert_to_html_tables.py b/.github/scripts/convert_to_html_tables.py
@@ -11,7 +11,26 @@
   > GitHub action variable: ${{ github.repository }}
 '''
 
+
 def find_table_points(lines):
+	"""
+	Find table points within a given list of lines.
+
+	The table points are determined by the presence of the markers:
+		<!-- TABLE BEGINS -->
+		<!-- TABLE ENDS -->
+
+	Args:
+		lines (list): List of lines to search in.
+
+	Returns:
+		tuple: A tuple of two integers containing the start and end indices of
+			the table points.
+
+	Raises:
+		SystemExit: If the table markers are not found or if the table end
+			marker appears before the table start marker.
+	"""
 
 	# Setting default return values
 	table_start = None
@@ -42,6 +61,18 @@ def find_table_points(lines):
 
 
 def main():
+	"""
+	Update the index.md file with the latest contributors data.
+
+	This function retrieves the REPO_NAME environment variable and the
+	CONTRIBUTORS_LOG file path. It then reads the log file and extracts the
+	data from it. The function then reads the index.md file and calculates
+	the table points. If the table does not exist, it creates the table
+	header. The function then iterates over the log data and updates the
+	table with the latest data. Finally, it updates the index.md file with
+	the updated data and prints a success message.
+
+	"""
 
 	# Retrieving Environmental variables
 	REPO_NAME = os.environ.get('REPO_NAME')
@@ -79,22 +110,29 @@ def main():
 
 		# Processing contributors-names
 		contributors_names = details['contributor-name']
-		contributors_names_list = [f'<a href="https://github.com/{name}" title="goto {name} profile">{name}</a>' for name in contributors_names]
+		contributors_names_list = [
+			f'<a href="https://github.com/{name}" title="goto {name} profile">{name}</a>' for name in contributors_names]
 		contributors_names_output = ', '.join(contributors_names_list)
 
 		# Processing pull-requests
 		pull_requests = details['pull-request-number']
-		pull_requests_list = [f'<a href="https://github.com/{REPO_NAME}/pull/{pr}" title="visit pr \#{pr}">{pr}</a>' for pr in pull_requests]
+		pull_requests_list = [
+			f'<a href="https://github.com/{REPO_NAME}/pull/{pr}" title="visit pr \#{pr}">{pr}</a>' for pr in pull_requests]
 		pull_requests_output = ', '.join(pull_requests_list)
 
 		# Processing demo-path
 		demo_path = details['demo-path']
 		if ' ' in demo_path:
 			demo_path = '%20'.join(demo_path.split())
-		demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/{title}/</a>' 
+		demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/{title}/</a>'
 		if title == 'root' or title == '{init}':
-			demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/</a>' 
-		
+			demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/</a>'
+		elif title == '{workflows}':
+			demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/.github/workflows</a>'
+		elif title == '{scripts}':
+			demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/.github/scripts</a>'
+		elif title == '{others}':
+			demo_path_output = f'<a href="{demo_path}" title="view the result of {title}">/{REPO_NAME}/.github</a>'
 
 		# Appending all data together
 		updated_lines.append('\t<tr align="center">\n')
diff --git a/.github/scripts/update_contributors_log.py b/.github/scripts/update_contributors_log.py
@@ -15,7 +15,21 @@
   > GitHub action variable: ${{ github.event.pull_request.number }}
 '''
 
+
 def get_project_title(pr_data):
+	"""
+	Determines the project title based on the file paths in the pull request data.
+
+	Args:
+			pr_data (dict): The pull request data containing file paths.
+
+	Returns:
+			str: The project title derived from the directory name in the file path.
+						Returns 'root' if changes are made in the root of the repository.
+						Special cases include '{workflows}', '{scripts}', and '{others}'
+						for certain paths within the '.github' directory.
+
+    """
 
 	# Setting default value
 	project_title = 'root'
@@ -26,16 +40,45 @@ def get_project_title(pr_data):
 			project_title = i["path"]
 			break
 
-	# If we find a directory
-	if project_title != 'root':
-		project_title = project_title.split('/')[0]
+	# changes are made in the root of repo
+	if project_title == 'root':
+		return project_title
+
+	if '.github/workflows' in project_title:
+		project_title = '{workflows}'
+	elif '.github/scripts' in project_title:
+		project_title = '{scripts}'
+	elif '.github' in project_title:
+		project_title = '{others}'
+	else:
+		project_title = project_title.split('/')[0]  # directory name
 
 	return project_title
 
+
 def get_contributor_name(pr_data):
+	"""
+	Retrieves the username of the contributor who made the pull request.
+
+	Args:
+		pr_data (dict): The pull request data containing the author's username.
+
+	Returns:
+		str: The username of the contributor.
+	"""
 	return pr_data["author"]["login"]
 
+
 def get_demo_path(pr_data):
+	"""
+	Retrieves the demo path for the pull request.
+
+	Args:
+		pr_data (dict): The pull request data containing information about the pull request.
+
+	Returns:
+		str: The demo path of the pull request.
+	"""
 
 	# Getting required values
 	REPO_NAME = os.environ.get('REPO_NAME')
@@ -45,8 +88,17 @@ def get_demo_path(pr_data):
 	if PROJECT_NAME == 'root':
 		return f'https://github.com/{REPO_NAME}/'
 
+	url_path = PROJECT_NAME
+
+	# Setting custom path for workflow maintance
+	SPECIAL_CASES = ['{workflows}', '{scripts}', '{others}']
+	if PROJECT_NAME in SPECIAL_CASES:
+		url_path = '.github'
+		if PROJECT_NAME in SPECIAL_CASES[:2]:
+			url_path += f'/{PROJECT_NAME[1:-1]}'
+
 	# Setting default value
-	demo_path = f'https://github.com/{REPO_NAME}/tree/main/{PROJECT_NAME}' 
+	demo_path = f'https://github.com/{REPO_NAME}/tree/main/{url_path}'
 	found_required_path = False
 
 	# Iterating through the "files" list
@@ -56,7 +108,7 @@ def get_demo_path(pr_data):
 			demo_path = path
 			found_required_path = True
 			break
-		elif  path.lower().endswith('index.md') or path.lower().endswith('readme.md'):
+		elif path.lower().endswith('index.md') or path.lower().endswith('readme.md'):
 			demo_path = path
 			found_required_path = True
 
@@ -70,7 +122,26 @@ def get_demo_path(pr_data):
 
 	return demo_path
 
+
 def main():
+	"""
+	Updates the contributors log file after a pull request has been merged.
+
+	This function is to be called in a GitHub Actions workflow after a pull request has been merged.
+	It reads the details of the current pull request from a JSON file, extracts the required information,
+	and updates the contributors log file accordingly.
+
+	The contributors log file is a JSON file that contains information about each contributor, including
+	their name, the number of the pull request they contributed to, and the path to their project.
+
+	The function dumps the data into the log file and outputs a success message upon completion.
+
+	Args:
+		None
+
+	Returns:
+		None
+	"""
 
 	# Setting required file paths
 	CURRENT_PR_DETAILS_PATH = 'pr.json'
@@ -125,5 +196,6 @@ def main():
 	# Output message
 	print(f'Successfully {operation_name} the log file')
 
+
 if __name__ == '__main__':
-	main()
+	main()
diff --git a/.github/scripts/update_index_md.py b/.github/scripts/update_index_md.py
@@ -11,7 +11,26 @@
   > GitHub action variable: ${{ github.repository }}
 '''
 
+
 def find_table_points(lines):
+	"""
+	Find table points within a given list of lines.
+
+	The table points are determined by the presence of the markers:
+		<!-- TABLE BEGINS -->
+		<!-- TABLE ENDS -->
+
+	Args:
+		lines (list): List of lines to search in.
+
+	Returns:
+		tuple: A tuple of two integers containing the start and end indices of
+			the table points.
+
+	Raises:
+		SystemExit: If the table markers are not found or if the table end
+			marker appears before the table start marker.
+	"""
 
 	# Setting default return values
 	table_start = None
@@ -42,6 +61,18 @@ def find_table_points(lines):
 
 
 def main():
+	"""
+	Update the index.md file with the latest contributors data.
+
+	This function retrieves the REPO_NAME environment variable and the
+	CONTRIBUTORS_LOG file path. It then reads the log file and extracts the
+	data from it. The function then reads the index.md file and calculates
+	the table points. If the table does not exist, it creates the table
+	header. The function then iterates over the log data and updates the
+	table with the latest data. Finally, it updates the index.md file with
+	the updated data and prints a success message.
+
+	"""
 
 	# Retrieving Environmental variables
 	REPO_NAME = os.environ.get('REPO_NAME')
@@ -64,7 +95,8 @@ def main():
 	# Creating table header if doesn't exist
 	if table_end - table_start == 1:
 		table_header = list()
-		table_header.append('| Project Title | Contributor Names | Pull Requests | Demo |\n')
+		table_header.append(
+			'| Project Title | Contributor Names | Pull Requests | Demo |\n')
 		table_header.append('| --- | --- | --- | --- |\n')
 		lines[table_start+1:table_end] = table_header
 
@@ -76,12 +108,14 @@ def main():
 
 		# Processing contributors-names
 		contributors_names = details['contributor-name']
-		contributors_names_list = [f'[{name}](https://github.com/{name} "goto {name} profile")' for name in contributors_names]
+		contributors_names_list = [
+			f'[{name}](https://github.com/{name} "goto {name} profile")' for name in contributors_names]
 		contributors_names_output = ', '.join(contributors_names_list)
 
 		# Processing pull-requests
 		pull_requests = details['pull-request-number']
-		pull_requests_list = [f'[#{pr}](https://github.com/{REPO_NAME}/pull/{pr} "visit pr \#{pr}")' for pr in pull_requests]
+		pull_requests_list = [
+			f'[#{pr}](https://github.com/{REPO_NAME}/pull/{pr} "visit pr \#{pr}")' for pr in pull_requests]
 		pull_requests_output = ', '.join(pull_requests_list)
 
 		# Processing demo-path
@@ -91,9 +125,16 @@ def main():
 		demo_path_output = f'[/{REPO_NAME}/{title}/]({demo_path} "view the result of {title}")'
 		if title == 'root' or title == '{init}':
 			demo_path_output = f'[/{REPO_NAME}/]({demo_path} "view the result of {title}")'
+		elif title == '{workflows}':
+			demo_path_output = f'[/{REPO_NAME}/.github/workflows]({demo_path} "view the result of {title}")'
+		elif title == '{scripts}':
+			demo_path_output = f'[/{REPO_NAME}/.github/scripts]({demo_path} "view the result of {title}")'
+		elif title == '{others}':
+			demo_path_output = f'[/{REPO_NAME}/.github]({demo_path} "view the result of {title}")'
 
 		# Appending all data together
-		updated_lines.append(f'| {title} | {contributors_names_output} | {pull_requests_output} | {demo_path_output} |\n')
+		updated_lines.append(
+			f'| {title} | {contributors_names_output} | {pull_requests_output} | {demo_path_output} |\n')
 
 	# Updating the lines with updated data
 	lines[table_start+3:table_end] = updated_lines
