Update setup instructions

- Move MacOS instructions from interface to setup
- Update instructions to use the xlwings.config file rather than the ribbon tab
- Use Conda path and Conda env rather than interpreter path
- Other minor edits

docs/source/interface.rst

@@ -3,9 +3,9 @@ User Interface
 ====================
 
 Tour of the user interface:
---------------
+---------------------------
 
-The user interface is located in the folder **'EnergyPATHWAYS\\EP interface'** and has two files. The first is a file called scenario_builder.py, which is a python file that must be located together with the excel sheet but that most users do not need to directly interact with. The second file is scenario_builder.xlsm, which is an excel workbook that organizes running the model.
+The user interface is located in the folder **EnergyPATHWAYS\\EP interface** and has two files. The first is a file called scenario_builder.py, which is a python file that must be located together with the excel sheet but that most users do not need to directly interact with. The second file is scenario_builder.xlsm, which is an excel workbook that organizes running the model.
 
 The excel workbook aids with three things:
 
@@ -15,6 +15,10 @@ The excel workbook aids with three things:
 
 The youtube videos below walk through the basic use of the user interface.
 
+.. note:: 
+ On MacOS you cannot use the scenario_builder.xlsm file to run EnergyPATHWAYS. See the :ref:`Run Energy Pathways on MacOS` section for instructions on how to use the start_runs.sh bash script, which provides a similar service. 
+
+
 Interface Overview
 ==================
 
@@ -60,8 +64,8 @@ Interface Debugging
  <iframe width="560" height="315" src="https://www.youtube.com/embed/8evvCluebMg?si=dNKXHDZf1AzyJ6Yf" frameborder="0" allowfullscreen></iframe>
  </div>
 
-Configuration options
----------------------
+Configuration file options
+--------------------------
 
 The configuration file is a text file that contains all the configuration options for the model. The configuration file is divided into sections, each of which contains a number of options with values that define how the model will run.
 
@@ -154,22 +158,9 @@ The configuration file is a text file that contains all the configuration option
  log_level = INFO
  stdout = True
 
-Additional configuration for MacOS users
-----------------------------------------
-
-1. Install the ``xlwings`` Excel Add-in by running the following command in the terminal::
- 
- (ep) $ xlwings addin install
-
-2. Inside the EP interface folder, open the ``scenario_builder.xlsm`` file with Excel
-3. Enable the developer tab on the ribbon by going to ``Excel > Preferences > Ribbon & Toolbar``
-4. Open the VBA editor
-5. Remove the ``xlwings`` module inside the ``VBAProject (scenario_builder.xlsm)`` project
-6. Under ``Tools > References``, find and check the ``xlwings`` reference
-7. Find the path to the Python interpreter of the ``ep`` environment and copy it to the ``Interpreter`` field of the ``xlwings`` tab
 
-Run Energy Pathways
-===================
+Run Energy Pathways on MacOS
+-----------------------------
 
 Once the cases are set up, the model can be run by using the ``start_runs.sh`` script located in the ``EP interface`` folder. 
 

docs/source/setup.rst

@@ -22,6 +22,8 @@ If you want a smaller conda installation or are not on windows, feel free to dow
 .. Note::
  EnergyPATHWAYS has been developed and tested primarily on Microsoft Windows and the interface requires Microsoft Excel. Some of the Excel interface features can be used on a Mac, and a shell script is now available to run cases on Mac or Linux.
 
+ **All prompt commands on Windows should be run in the Anaconda Prompt.**
+
 Model outputs consist of large csv files that have been designed to work well with `Tableau <https://www.tableau.com/>`_.
 
 
@@ -30,26 +32,56 @@ Installation
 EnergyPATHWAYS can be installed using the ``environment.yml`` file provided in the repository. This file contains all the necessary packages to run EnergyPATHWAYS. To install the environment, navigate to the directory containing the ``environment.yml`` file and run the following commands::
 
  $ cd EnergyPATHWAYS
- $ conda env create -f environment.yml -n ep
+ $ conda env create -f environment.yml
 
 This will create a new environment called ``ep``. Then, activate the environment and install EnergyPATHWAYS::
 
  $ conda activate ep
  $ pip install -e .
 
-Alternatively, EnergyPATHWAYS can be installed using Python's setuptools.
+Using the ``-e`` flag will install EnergyPATHWAYS inside your new ``ep`` conda environment in editable mode so that any changes to the code are reflected when running EnergyPATHWAYS without having to reinstall.
+
+After running the setup script, the excel interface will be able to call the EnergyPATHWAYS model. It will also make the command line function ``energyPATHWAYS`` available.
+
+.. tip::
+
+ If you get permissions errors on a Windows machine during the installation process, right click on the Anaconda Prompt and select the option *Run as administrator*.
+
+ If you encounter an error saying *ERROR: <folder name> does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found,* check to make sure you are in the correct directory. If you run ``ls`` (or ``dir`` on Windows) at the command prompt you should see the ``environment.yml`` and ``pyproj.toml`` files.
+
+Additional Excel configuration
+------------------------------
+
+For all users
+^^^^^^^^^^^^^^^
+
+1. (Optional, **depreciated**) Install the ``xlwings`` Excel Add-in by running the following command in the terminal::
+ 
+ (ep) $ xlwings addin install
+
+Installing the xlwings addin will add a new ribbon tab to your Excel files. We have started using an "xlwings.conf" sheet in the scenario_builder.xlsm file instead of the ribbon tab.
+
+2. Enter the "Conda path" and "Conda env" values on the "xlwings.conf" sheet of your scenario_builder.xlsm file. Find the path to your Conda "base environment" ::
+ 
+ (ep) $ conda info
 
-After cloning the EnergyPATHWAYS repository::
+The Conda path should be something like ``C:\Users\Username\Anaconda3`` (Windows) or ``/Users/Username/miniconda3`` (MacOS). Copy this path to the "Conda path" field on your xlwings.conf sheet. Assuming you have followed installation instructions up to this point, use ``ep`` as the "Conda env".
 
- > python setup.py develop
+.. note:: 
+ On a Windows machine, the "Conda path" and "Conda env" variables will be used to activate your conda environment before running energyPATHWAYS. The "Start Runs" button in your scenario_builder.xlsm file will likely not work if you do not provide these values.
+
+ For more information on using the Xlwings ribbon and "xlwings.conf" sheet, see the `xlwings addin documentation <https://docs.xlwings.org/en/latest/addin.html>`_.
 
-After running the setup script, the excel interface will be able to call the EnergyPATHWAYS model.
 
-.. topic:: Troubleshooting
+For MacOS users
+^^^^^^^^^^^^^^^
 
- Running setup.py develop will often give permissions errors. To address this, it is recommended that you right click on the command prompt and select the option *Run as administrator*.
+1. Inside the EP interface folder, open the ``scenario_builder.xlsm`` file with Excel
+2. Enable the developer tab on the ribbon by going to ``Excel > Preferences > Ribbon & Toolbar``
+3. Open the VBA editor
+4. Remove the ``xlwings`` module inside the ``VBAProject (scenario_builder.xlsm)`` project
+5. Under ``Tools > References``, find and check the ``xlwings`` reference
 
- If you encounter an error saying *ERROR: <folder name> does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found,* check to make sure you are in the correct directory.
 
 Data Setup
 ==========
@@ -71,19 +103,17 @@ You can place EnergyPATHWAYS anywhere you want on your computer. We find that a
  Some-Date-EP_model
  ├── EnergyPATHWAYS
  │ ├── EnergyPATHWAYS
- │ └── setup.py
- ├── csvdb
- │ ├── numerous folders
- │ └── setup.py
+ │ └── pyproj.toml
  ├── EP_interface
  │ ├── scenario_builder.py
- │ └── scenario_builder.xlsm
+ │ ├── scenario_builder.xlsm
+ │ └── start_runs.sh
  ├── ep_db
  │ ├── ShapeData
  │ └── numerous csv files
  ├── ep_runs
  │ ├── my_scenario
- │ │ └── config.INI
+ │ │ ├── config.INI
  │ │ └── runs_key.csv
 
 Running the Model
@@ -97,4 +127,4 @@ To get help on the various command line options, use::
 
  $ energyPATHWAYS --help
 
-In most cases, the user interface, described in :doc:`Interface Section <interface>`, is the best way to interact with the model.
+In most cases, the Excel user interface, described in :doc:`Interface Section <interface>`, is the best way to interact with the model.