From 995d0e62ad094d188153dbfba6dcc0f57fda7fb5 Mon Sep 17 00:00:00 2001 From: Brad Crawford Date: Thu, 29 Jan 2026 11:21:05 -0500 Subject: [PATCH 1/2] updated documentation, README, and added unit-tests for the local docs build. --- README.md | 33 +- .../installation/installation.rst | 99 ++++- docs/index.rst | 13 +- docs/reference/units.rst | 5 +- .../tests/test_docs_build.py | 416 ++++++++++++++++++ 5 files changed, 539 insertions(+), 27 deletions(-) create mode 100644 python_github_tutorial/tests/test_docs_build.py diff --git a/README.md b/README.md index 1e2e728..4b92694 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Alternative software for `miniforge`: The python_github_tutorial package dependencies can be installed via conda, and this package tagged in conda via pip install: To perform the python_github_tutorial package build, please run the following commands -from the ``/python_github_tutorial`` directory. Create and install conda package: @@ -38,18 +38,20 @@ Activate the environment the environment `conda activate python_github_tutorial` -Install the developement enviroment +Install the developement environment `pip install -e .` -Note: If you update the conda package, you may have to redo the pip install. Without doing this, it may allow incompatable versions of the dependencies to be installed, etc.: +> [!NOTE] +> If you update the conda package, you may have to redo the pip install. Without doing this, it may allow incompatable versions of the dependencies to be installed, etc.: ## Run the example -This is an example of the supplimentary functions in the utils directory (``/python_github_tutorial/python_github_tutorial/utils``) and the main function in the main_functions directory (``/python_github_tutorial/python_github_tutorial/main_functions``). +The example (``examples.py``) is located here ``/python_github_tutorial/examples_to_run``. The instructions to run it are provided below: -The example is located here ``/python_github_tutorial/examples_to_run``. The instructions to run it are provided below: `cd examples_to_run` @@ -57,6 +59,8 @@ The example is located here ``/python_github_tutorial/examples_to_run``. + This is the same example but running it as an interactive job (i.e., like a Jupyter notebook). The example is located here 'examples_to_run/interactive_examples.py'. When using Visual Studios Code (VScode), the '# %%' above each section makes it a cell, which can be run individually by holding shift and pressing enter. @@ -69,7 +73,7 @@ The unit tests via ``pytest`` ensure that the code is build properly, running co accurate results. To perform these tests (unit tests) for the python_github_tutorial package, please run the following commands -from the ``/python_github_tutorial/python_github_tutorial/tests`` directory: Run all the tests: @@ -89,17 +93,24 @@ Run individual test on 'test_main_functions.py': `pytest test_main_functions.py` +Run individual test on 'test_docs_build.py': + +`cd python_github_tutorial/tests` + +`pytest test_docs_build.py` + ## Build the documentation (docs) Building these HTML files locally via sphinx, which will allow you to access them with your local internet browsing application or HTML viewer (chrome, safari, VScode, etc.). -The HTML files will be located in the ``/python_github_tutorial/docs/_build/html`` directory after they are built. The python_github_tutorial utilizes [sphinx](https://www.sphinx-doc.org/en/master/index.html) to construct the documentation. -The user can build the documentation locally by executing the following command from the ``docs`` directory: -To perform the documents (docs) build for the python_github_tutorial package, please run the following commands -from the ``/python_github_tutorial/docs`` directory: + + `conda activate python_github_tutorial` @@ -107,4 +118,6 @@ from the ``/python_github_tutorial/docs/_build/html`` directory after they are built. + You can find the docs `html` build here -> `docs/_build/html`. When in the `docs/_build/html` directory, click on any `html` file and it will open the full docs. diff --git a/docs/getting_started/installation/installation.rst b/docs/getting_started/installation/installation.rst index e67d183..69113dc 100644 --- a/docs/getting_started/installation/installation.rst +++ b/docs/getting_started/installation/installation.rst @@ -4,9 +4,20 @@ Installation Install an editable version from the source (GitHub) ---------------------------------------------------- + +This project's environment can be built using ``miniforge``. +Alternative software for ``miniforge``: +- You use can use ``anaconda`` or ``miniconda``, which use the same ``conda`` command. +- You use can use ``micromamba`` or ``mamba``, supplimenting ``micromamba`` or ``mamba`` respectively for ``conda`` when using them. + +The python_github_tutorial package dependencies can be installed via conda, and this package tagged in conda via pip install: + +To perform the python_github_tutorial package build, please run the following commands +from the ``/python_github_tutorial`` directory. + :: - $ cd path_to_first_python_github_tutorial_dirctory_with_environment_yml_file + $ cd python_github_tutorial $ conda env create -f environment.yml @@ -15,21 +26,58 @@ Install an editable version from the source (GitHub) $ pip install -e . +.. note:: + + If you update the conda package, you may have to redo the pip install. Without doing this, it may allow incompatable versions of the dependencies to be installed, etc.: + + +Run the Example +--------------- + +This is an example of the supplimentary functions in the utils directory (``/python_github_tutorial/python_github_tutorial/utils``) and the main function in the main_functions directory (``/python_github_tutorial/python_github_tutorial/main_functions``). +The example (``examples.py``) is located here ``/python_github_tutorial/examples_to_run``. The instructions to run it are provided below: + +:: + + $ cd examples_to_run + + $ python examples.py + +Run the Interactive Example in Visual Studios Code (VScode) +----------------------------------------------------------- + +This interactive example (``interactive_examples.py``) is located here ``/python_github_tutorial/examples_to_run``. + +This is the same example but running it as an interactive job (i.e., like a Jupyter notebook). The example is located here 'examples_to_run/interactive_examples.py'. + +When using Visual Studios Code (VScode), the '# %%' above each section makes it a cell, which can be run individually by holding shift and pressing enter. + + Building the HTML documenation files (GitHub) --------------------------------------------- -Building these HTML files locally via sphinx, which will allow you to access them with your -local internet browsing application or HTML viewer (chrome, safari, VScode, etc.). -The HTML files will be located in the ``docs/_build/html`` directory after they are built. +Building these HTML files locally via sphinx, which will allow you to access them with your +local internet browsing application or HTML viewer (chrome, safari, VScode, etc.). The python_github_tutorial utilizes `sphinx `_ to construct the documentation. -The user can build the documentation locally by executing the following command from the ``docs`` directory:: + +The user can build the documentation locally by executing the following command from the ``docs`` directory. +To perform the documents (docs) build for the python_github_tutorial package, please run the following commands from the ``/python_github_tutorial/docs`` directory: + +:: $ conda activate python_github_tutorial + $ cd docs + $ make html +After the files are built, the HTML files will be located in the ``/python_github_tutorial/docs/_build/html`` directory after they are built. + +You can find the docs `html` build here -> `docs/_build/html`. When in the `docs/_build/html` directory, click on any `html` file and it will open the full docs. + + Testing the software installation ---------------------------------- @@ -37,9 +85,40 @@ The python_github_tutorial software tests the installation using `pytest /python_github_tutorial/python_github_tutorial/tests`` directory: - $ conda activate python_github_tutorial - - $ pytest -v \ No newline at end of file + +Run all the tests: + +:: + + $ cd python_github_tutorial/tests + + $ pytest -v + + +Run individual test on 'test_math.py': + +:: + + $ cd python_github_tutorial/tests + + $ pytest test_math.py + + +Run individual test on 'test_main_functions.py': + +:: + + $ cd python_github_tutorial/tests + + $ pytest test_main_functions.py + +Run individual test on 'test_docs_build.py': + +:: + + $ cd python_github_tutorial/tests + + $ pytest test_docs_build.py diff --git a/docs/index.rst b/docs/index.rst index b0febfb..8b6e1e3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ This Github tutorial shows the following: * Code structure in a GitHub repository. * Setup and building GitHub documentation. -* Basic structure and docstring (code documentation) for Python functions and classes. +* Basic structure and docstrings for Python functions and classes. Code structure in a GitHub repository @@ -32,21 +32,22 @@ Setup and building GitHub documentation --------------------------------------- This Github repository shows a simple example of how GitHub documentation is created via sphinx. -This documentation can be build via `readthedocs `_ -for everyone to find on the internet. -This documentation can also be build locally via ``sphinx`` and the ``make html`` command in the ``docs`` +This documentation can also be build locally via `sphinx `_ and the ``make html`` command in the ``docs`` directory, which builds the html files locally that can be viewed in your local +This documentation can be build via `readthedocs `_ +for everyone to find on the internet using the same files and structure. internet browsing application or html viewer (chrome, safari, VScode, etc.). -Basic structure and docstring (code documentation) for Python functions and classes ------------------------------------------------------------------------------------ +Basic structure and docstrings for Python functions and classes +--------------------------------------------------------------- This Github repository demonstrates how to write object-oriented Python code using classes and functions. In addition to the code structure itself, it is also an example of how to write Python docstrings. Python docstrings are the documentation for the classes and functions, which describe the input variables, attributes, methods, and outputs/output variables. + .. toctree:: :caption: Overview :maxdepth: 2 diff --git a/docs/reference/units.rst b/docs/reference/units.rst index 1b65707..84c5b69 100644 --- a/docs/reference/units.rst +++ b/docs/reference/units.rst @@ -2,13 +2,16 @@ Units ===== -In this python_github_tutorial package, the input and output values are unitless (i.e., no units were used). +In this ``python_github_tutorial`` package, the input and output values are unitless (i.e., no units were used). If units were used in your software, you should specify them here and how they are utilized. This includes specifiying the unitless variables, so the user knows. A good code will test for the unit values and unitless values, minimizing user input error. .. note:: + + Scientists and Engineers may find this ``unyt`` python package useful. + The `unyt `_ can automatically convert units for you so the users can input any units, provided they are in the proper form. If the ``unyt`` package is used, it should be mentioned here, specifying where and diff --git a/python_github_tutorial/tests/test_docs_build.py b/python_github_tutorial/tests/test_docs_build.py new file mode 100644 index 0000000..15530f7 --- /dev/null +++ b/python_github_tutorial/tests/test_docs_build.py @@ -0,0 +1,416 @@ +import os,sys,inspect,subprocess + +from python_github_tutorial.tests.base_test import BaseTest + +# set the directiories and required packages +currentdir = os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe()))) +parentdir = os.path.dirname(currentdir) +grandparentdir = os.path.dirname(parentdir) +greatgrandparentdir = os.path.dirname(grandparentdir) +sys.path.insert(0,str(currentdir)) +sys.path.insert(0,str(parentdir)) +sys.path.insert(0,str(grandparentdir )) +sys.path.insert(0,str(greatgrandparentdir)) + +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.") + + build_docs_pipe = subprocess.Popen( + f"cd {doc_directory} && make html", + shell=True, + ) + + # check errors and wait + build_docs_pipe.communicate() + + # this is needed to capture any errors, as the subprocess alone will not. + print(f"test_file.returncode = {build_docs_pipe.returncode}") + if build_docs_pipe.returncode == 0: + docs_build_passed_bool = True + else: + print("Test failed") + docs_build_passed_bool = False + + print("***********************************") + assert docs_build_passed_bool is True + + # ****************************************** + # BUILD THE DOCS (END) + # ****************************************** + + # ****************************************** + # Test the HTML file are built (START) + # ****************************************** + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + 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.") + + # 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}" + 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 + + + # ****************************************** + # 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 8a98bf2b956016fc52b970cff62a4d462d6ce57f Mon Sep 17 00:00:00 2001 From: Brad Crawford Date: Thu, 29 Jan 2026 11:43:01 -0500 Subject: [PATCH 2/2] modified environments to use only conda-forge and pip, and changed the conf.py to remove sphinx packages that are deprecated. --- docs/conf.py | 4 ---- docs/environment_docs.yml | 18 +++++++++--------- environment.yml | 8 +++----- 3 files changed, 12 insertions(+), 18 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1b37f63..8393673 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -171,10 +171,6 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'default' -import sphinx_rtd_theme - -html_theme = "sphinx_rtd_theme" -hhtml_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/environment_docs.yml b/docs/environment_docs.yml index 19cc2a2..1e92123 100644 --- a/docs/environment_docs.yml +++ b/docs/environment_docs.yml @@ -1,23 +1,23 @@ name: python_github_tutorial_docs channels: - conda-forge - - defaults dependencies: - - python + - python=3.12.* - numpy - pytest - - pip + - pytest-cov + - coverage - mock - - ipython - - nbconvert - - jupyter + - ipython + - nbconvert + - jupyter - pygments - numpydoc - - sphinx=6.1.1 - - sphinx_rtd_theme + - sphinx - nbsphinx - - sphinxcontrib + - pip - pip: + - sphinxcontrib-packages - sphinxcontrib-svg2pdfconverter - sphinxcontrib-video - sphinxcontrib-serializinghtml diff --git a/environment.yml b/environment.yml index 5e69616..24fb015 100644 --- a/environment.yml +++ b/environment.yml @@ -1,14 +1,12 @@ name: python_github_tutorial channels: - conda-forge - - defaults dependencies: - - python + - python=3.12.* - numpy - pytest - pytest-cov - coverage - - pip - mock - ipython - nbconvert @@ -16,10 +14,10 @@ dependencies: - pygments - numpydoc - sphinx - - sphinx_rtd_theme - nbsphinx - - sphinxcontrib + - pip - pip: + - sphinxcontrib-packages - sphinxcontrib-svg2pdfconverter - sphinxcontrib-video - sphinxcontrib-serializinghtml