From 125a97769185978c069659000546aa448501c37e Mon Sep 17 00:00:00 2001 From: Brad Crawford Date: Fri, 30 Jan 2026 08:22:50 -0500 Subject: [PATCH 1/2] Simplified docs unit-test code by adding a function, minimizing reused code. --- .../tests/test_docs_build.py | 332 +++++++----------- 1 file changed, 133 insertions(+), 199 deletions(-) diff --git a/python_github_tutorial/tests/test_docs_build.py b/python_github_tutorial/tests/test_docs_build.py index 15530f7..ab0eb1b 100644 --- a/python_github_tutorial/tests/test_docs_build.py +++ b/python_github_tutorial/tests/test_docs_build.py @@ -12,28 +12,50 @@ sys.path.insert(0,str(grandparentdir )) sys.path.insert(0,str(greatgrandparentdir)) +def find_directory(find_directory_name): + """Find a directory full path by looking at the current directory and, a few directories backwards. + + This function finds a directory's full path looking at the current, parent, + grandparent, and greatgrandparent directories. + + Parameters + ---------- + find_directory_name: str + The directory name that you want find the full path of. + + Returns + ------- + full_directory_path: str + The full path of the directory name you want to find (i.e., 'find_directory_name') + """ + if not isinstance(find_directory_name, str): + TypeError(f"ERROR: The 'find_directory_name' is a {type(find_directory_name)}, not a str.") + + if os.path.isdir(f"{currentdir}/{find_directory_name}") is True: + full_directory_path = f"{currentdir}/{find_directory_name}" + elif os.path.isdir(f"{parentdir}/{find_directory_name}") is True: + full_directory_path = f"{parentdir}/{find_directory_name}" + elif os.path.isdir(f"{grandparentdir}/{find_directory_name}") is True: + full_directory_path = f"{grandparentdir}/{find_directory_name}" + elif os.path.isdir(f"{greatgrandparentdir}/{find_directory_name}") is True: + full_directory_path = f"{greatgrandparentdir}/{find_directory_name}" + else: + IndexError("ERROR: The 'docs' directory location not found.") + + return full_directory_path + class TestDocsBuild(BaseTest): # ****************************************** # BUILD THE DOCS (START) # ****************************************** - # # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") - + # find the 'doc' directories relative path (needed for running pytest in various locations) + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + build_docs_pipe = subprocess.Popen( - f"cd {doc_directory} && make html", + f"cd {full_dir_path} && make html", shell=True, ) @@ -61,24 +83,19 @@ class TestDocsBuild(BaseTest): def test_doc_search_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html" doc_filename = "search.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -88,24 +105,19 @@ def test_doc_search_html_built(self): def test_doc_search_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html" doc_filename = "search.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -115,24 +127,19 @@ def test_doc_search_html_built(self): def test_doc_file_installation_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/getting_started/installation" doc_filename = "installation.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -142,24 +149,19 @@ def test_doc_file_installation_html_built(self): def test_doc_file_add_2_numbers_example_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/getting_started/quick_start" doc_filename = "add_2_numbers_example.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -169,24 +171,19 @@ def test_doc_file_add_2_numbers_example_html_built(self): def test_doc_file_math_function_class_example_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/getting_started/quick_start" doc_filename = "math_function_class_example.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -196,24 +193,19 @@ def test_doc_file_math_function_class_example_html_built(self): def test_doc_file_quick_start_toc_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/getting_started/quick_start" doc_filename = "quick_start_toc.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -223,24 +215,19 @@ def test_doc_file_quick_start_toc_html_built(self): def test_doc_file_tutorials_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/getting_started/quick_start" doc_filename = "tutorials.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -250,24 +237,19 @@ def test_doc_file_tutorials_html_built(self): def test_doc_file_general_info_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/overview" doc_filename = "general_info.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -277,24 +259,19 @@ def test_doc_file_general_info_html_built(self): def test_doc_file_citing_python_github_tutorial_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/reference" doc_filename = "citing_python_github_tutorial.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -304,24 +281,19 @@ def test_doc_file_citing_python_github_tutorial_html_built(self): def test_doc_file_units_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/reference" doc_filename = "units.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -331,24 +303,19 @@ def test_doc_file_units_html_built(self): def test_doc_data_structures_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/topic_guides" doc_filename = "data_structures.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -358,24 +325,19 @@ def test_doc_data_structures_html_built(self): def test_doc_specific_topic_guides_html_built(self): # find the 'doc' directories relative path (needed for running pytest in various locations) - start_test_doc_directory = "docs" - - if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" - elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" - elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" - elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" - else: - IndexError("ERROR: The 'docs' directory location not found.") + search_for_directory = "docs" + full_dir_path = find_directory(search_for_directory) + + build_docs_pipe = subprocess.Popen( + f"cd {full_dir_path} && make html", + shell=True, + ) # add the 'docs' subfolder location and the filname doc_sub_directory = "_build/html/topic_guides" doc_filename = "specific_topic_guides.html" - doc_file_path = f"{doc_directory}/{doc_sub_directory}" + doc_file_path = f"{full_dir_path}/{doc_sub_directory}" is_dir_bool = os.path.isdir(doc_file_path) is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") @@ -386,31 +348,3 @@ def test_doc_specific_topic_guides_html_built(self): # ****************************************** # Test the HTML file are built (END) # ****************************************** - -""" -# find the 'doc' directories relative path (needed for running pytest in various locations) -start_test_doc_directory = "docs" - -if os.path.isdir(f"{currentdir}/{'docs'}") is True: - doc_directory = f"{currentdir}/{'docs'}" -elif os.path.isdir(f"{parentdir}/{'docs'}") is True: - doc_directory = f"{parentdir}/{'docs'}" -elif os.path.isdir(f"{grandparentdir}/{'docs'}") is True: - doc_directory = f"{grandparentdir}/{'docs'}" -elif os.path.isdir(f"{greatgrandparentdir}/{'docs'}") is True: - doc_directory = f"{greatgrandparentdir}/{'docs'}" -else: - IndexError("ERROR: The 'docs' directory location not found.") - -doc_sub_directory = "_build/html" -doc_filename = "search.html" - -doc_file_path = f"{doc_directory}/{doc_sub_directory}" -is_dir_bool = os.path.isdir(doc_file_path) -is_file_bool = os.path.isfile(f"{doc_file_path}/{doc_filename}") - - -assert is_dir_bool is True -assert is_file_bool is True - -""" \ No newline at end of file From fee41ca52389ad957b40b15b9388aed55907f3b9 Mon Sep 17 00:00:00 2001 From: Brad Crawford Date: Fri, 30 Jan 2026 08:23:36 -0500 Subject: [PATCH 2/2] Simplified docs unit-test code by adding a function, minimizing reused code. --- python_github_tutorial/tests/test_docs_build.py | 1 + 1 file changed, 1 insertion(+) diff --git a/python_github_tutorial/tests/test_docs_build.py b/python_github_tutorial/tests/test_docs_build.py index ab0eb1b..67e834f 100644 --- a/python_github_tutorial/tests/test_docs_build.py +++ b/python_github_tutorial/tests/test_docs_build.py @@ -44,6 +44,7 @@ def find_directory(find_directory_name): return full_directory_path + class TestDocsBuild(BaseTest): # ******************************************