Fixup docs, they could always use more, but its a lot better

README.md

@@ -12,41 +12,38 @@ Developers often propose changes to EnergyPlus for:
  - New feature development
  - Defect repair
  - Refactoring for structure or performance
- - etc.
 
-When a developer proposes these changes, they must be tested.
-The continuous integration system over on EnergyPlus handles this, and provides results, but there can be a long time delay waiting on those results, depending on how busy CI is at that moment.
-This tool provides a way to run these regressions locally.
+When a developer proposes these changes, those code changes must be tested prior to accepting them into the main branch.
+A continuous integration system runs the tests and provides results, but there can be a sometimes lengthy delay waiting on those results, depending on how busy the system is at that time.
+This set of tools provides a way to run these regressions locally.
 
-## Platform Support
+## Usage
 
-This tool is written to be functional on all three major platforms.
-Travis is testing the underlying code on all the platforms, and the developer regularly tests the graphical engine on all three as well.
-Packages are provided for two LTS versions of Ubuntu (18.04 and 20.04) as well as Windows and Mac.
+This tool works on all three major platforms: Windows, Mac, and Ubuntu LTS (18.04 and 20.04).
+Travis runs tests on all the platforms, and it is regularly used on all three as well.
 
-## Installation
-
-Ultimately there will be two ways to install this tool:
- - Downloading a pre-built (by Travis) binary package through a Github release page, and
- - Installing the library into an existing Python install using Pip.
-
-Right now the Pip implementation is not yet done, so the core method will be to download the binary.
-You should not need any outside tools to run the downloaded package, not even Python.
+There are two ways to install this tool:
+ - Download a pre-built (by Travis) binary package through a Github release [page](https://github.com/NREL/EnergyPlusRegressionTool/releases/latest).
+   - The user should not need any extra tools, including Python itself.
+   - The downloaded package should be extracted and then the extracted binary should be run directly.
+ - Install the library into an existing Python install using Pip (`pip install energyplusregressiontool`).
+   - Obviously the user will need the existing Python install, but other dependencies are automatically installed by Pip.
+   - Once installed into the Python install, there will be a binary available to run: `eplus_regression_runner`. 
 
 ## Development
 
-For setting up a development environment to actually _work_ on this tool, the steps are pretty minimal:
+For setting up a development environment to do _work_ on this tool, the steps are pretty minimal:
  - Install Python, if needed
  - Clone this repository (`git clone https://github.com/NREL/EnergyPlusRegressionTool`)
  - Install dependencies (`pip3 install -r requirements.txt`)
 
 ## Documentation
 
-Further program documentation, including user guide and typical workflows, are available in the documentation.
+Program documentation, including user guide and typical workflows, are available in the documentation.
 This documentation is written using RST with Sphinx, and published on [ReadTheDocs](https://energyplusregressiontool.readthedocs.io/en/latest/).
 
 ## Testing
 
 Exhaustive unit tests have been added to the "underneath the hood" code, like the functions that calculate diffs and run builds.
-GUI code is not unit tested, but tested manually on all platforms periodically.
 The unit tests are run by [Travis](https://travis-ci.org/NREL/EnergyPlusRegressionTool).
+The GUI code is not unit tested, but tested routinely on all platforms.

docs/run_cli.rst

@@ -14,16 +14,15 @@ Running build\_files\_to\_run.py
 In order to run a test suite, the main suite engine must know what files
 are to be run. The build\_files\_to\_run script generates a file to be
 used later by the test suite engine, that contains a properly formatted
-listing of files to be run. The basic operation is shown in Figure
-[fig:cmdprocess].
+listing of files to be run. The basic operation is shown in the following figure:
 
 .. figure:: Images/RunFromCommandLineProcess.jpg
    :alt: Utilizing the build\_files\_to\_run script to generate file list
 
    High level overview of utilizing the build\_files\_to\_run script to
    generate a list of files for a test suite
 
-Figure [fig:cmdprocess] shows how the process begins by combining the
+This figure shows how the process begins by combining the
 master csv file which lists all the details about the idf set with a set
 of user options such as "Don’t run files with external interface dependence,
 and select a random set of 7". The script process these two inputs, and

docs/run_gui.rst

@@ -14,10 +14,10 @@ Starting the GUI program will depend on how the package is installed/downloaded.
 
 - Downloaded binary from Github release page:
   - In this case, the user will simply run the downloaded binary
-- In the future, a pip installation will be available:
-  - In this case, a binary will be installed with the package that will allow running the GUI
+- Installed via Pip:
+  - In this case, a binary (`eplus_regression_runner`) will be installed with the package that will allow running the GUI
 - Cloned the repo for development:
-  - In this case, the user will run the `eplus_regression_runner` script at the root of the repo
+  - In this case, the user will run the `epregressions/runner.py` script at the root of the repo
 
 In some cases, a command window is launched prior to showing the graphical interface.
 This can be ignored.  When the GUI launches, it should look similar to this figure.
@@ -97,8 +97,7 @@ Last Run Summary & Re-do-ing
 ----------------------------
 
 When a test suite is completed, the GUI processes the results into a
-useful high-level results structure. This is shown in
-Figure [fig:screenshotsummary].
+useful high-level results structure. This is shown in the following figure:
 
 .. figure:: Images/ScreenshotSummary.png
    :alt: Screenshot of the summary window of the GUI after a suite was completed

epregressions/epw_map.py

@@ -776,6 +776,6 @@ def get_epw_for_idf(repo_source_dir: str, idf: str) -> Union[None, str]:
             return None
     else:
         # it appears we have an e+ install folder, try to look up the value, return None if not found
-        return epw_map.get(idf, default=None)
+        return epw_map.get(idf, None)
     # if something went really awry, just return None to use to the default
     return None

epregressions/tk_window.py

@@ -19,9 +19,11 @@
     filedialog, simpledialog,  # system dialogs
 )
 from typing import List, Union
+import webbrowser
 
 from pubsub import pub
 
+from epregressions import VERSION
 from epregressions.epw_map import get_epw_for_idf
 from epregressions.runtests import TestRunConfiguration, SuiteRunner
 from epregressions.structures import (
@@ -167,17 +169,21 @@ def __init__(self):
 
     def init_window(self):
         # changing the title of our master widget
-        self.root.title("EnergyPlus Regression Tool 2")
+        self.root.title("EnergyPlus Regression Tool")
         self.root.protocol("WM_DELETE_WINDOW", self.client_exit)
 
         # create the menu
         menu = Menu(self.root)
         self.root.config(menu=menu)
         file_menu = Menu(menu)
-        file_menu.add_command(label="Open Project", command=self.client_open)
-        file_menu.add_command(label="Save Project", command=self.client_save)
+        file_menu.add_command(label="Open Project...", command=self.client_open)
+        file_menu.add_command(label="Save Project...", command=self.client_save)
         file_menu.add_command(label="Exit", command=self.client_exit)
         menu.add_cascade(label="File", menu=file_menu)
+        help_menu = Menu(menu)
+        help_menu.add_command(label="Open Documentation...", command=self.open_documentation)
+        help_menu.add_command(label="About...", command=self.about_dialog)
+        menu.add_cascade(label="Help", menu=help_menu)
 
         # main notebook holding everything
         main_notebook = ttk.Notebook(self.root)
@@ -447,6 +453,20 @@ def open_file_browser_to_directory(dir_to_open):
                 print(this_exception)
         return p
 
+    @staticmethod
+    def open_documentation():
+        url = 'https://energyplusregressiontool.readthedocs.io/en/latest/'
+        # noinspection PyBroadException
+        try:
+            webbrowser.open_new_tab(url)
+        except Exception:
+            # error message
+            messagebox.showerror("Docs problem", "Could not open documentation in browser")
+
+    @staticmethod
+    def about_dialog():
+        messagebox.showinfo("About", f"EnergyPlus Regression Tool\nVersion: {VERSION}")
+
     def build_idf_listing(self, initialize=False, desired_selected_idfs: List[str] = None):
         # if we don't have a specific list, then try to save any already selected ones first
 
@@ -548,8 +568,10 @@ def build_results_tree(self, results: CompletedStructure = None):
         self.last_results = results
 
     def add_to_log(self, message):
-        self.log_message_listbox.insert(END, f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}]: {message}")
-        self.label_string.set(message)
+        if self.log_message_listbox:
+            self.log_message_listbox.insert(END, f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}]: {message}")
+        if self.label_string:
+            self.label_string.set(message)
 
     def clear_log(self):
         self.log_message_listbox.delete(0, END)
@@ -668,14 +690,18 @@ def set_gui_status_for_run(self, is_running: bool):
     def try_to_set_build_1_to_dir(self, selected_dir) -> bool:
         probable_build_dir_type = autodetect_build_dir_type(selected_dir)
         if probable_build_dir_type == KnownBuildTypes.Unknown:
+            self.add_to_log("Could not detect build 1 type")
             return False
         elif probable_build_dir_type == KnownBuildTypes.Installation:
+            self.add_to_log("Build 1 type detected as an EnergyPlus Install")
             self.build_1 = EPlusInstallDirectory()
             self.build_1.set_build_directory(selected_dir)
         elif probable_build_dir_type == KnownBuildTypes.VisualStudio:
+            self.add_to_log("Build 1 type detected as a Visual Studio build")
             self.build_1 = CMakeCacheVisualStudioBuildDirectory()
             self.build_1.set_build_directory(selected_dir)
         elif probable_build_dir_type == KnownBuildTypes.Makefile:
+            self.add_to_log("Build 1 type detected as a Makefile-style build")
             self.build_1 = CMakeCacheMakeFileBuildDirectory()
             self.build_1.set_build_directory(selected_dir)
         return True
@@ -698,14 +724,18 @@ def client_build_dir_1(self):
     def try_to_set_build_2_to_dir(self, selected_dir) -> bool:
         probable_build_dir_type = autodetect_build_dir_type(selected_dir)
         if probable_build_dir_type == KnownBuildTypes.Unknown:
+            self.add_to_log("Could not detect build 2 type")
             return False
         elif probable_build_dir_type == KnownBuildTypes.Installation:
+            self.add_to_log("Build 2 type detected as an EnergyPlus Install")
             self.build_2 = EPlusInstallDirectory()
             self.build_2.set_build_directory(selected_dir)
         elif probable_build_dir_type == KnownBuildTypes.VisualStudio:
+            self.add_to_log("Build 2 type detected as a Visual Studio build")
             self.build_2 = CMakeCacheVisualStudioBuildDirectory()
             self.build_2.set_build_directory(selected_dir)
         elif probable_build_dir_type == KnownBuildTypes.Makefile:
+            self.add_to_log("Build 2 type detected as a Makefile-style build")
             self.build_2 = CMakeCacheMakeFileBuildDirectory()
             self.build_2.set_build_directory(selected_dir)
         return True