Update README.rst

README.rst

@@ -66,8 +66,128 @@ Useful links
 Installation
 ============
 
-Using ``pip``
--------------
+Supported Python Versions
+-------------------------
+
+The most recent version of GerryChain (as of February 2024) supports
+
+- Python 3.9
+- Python 3.10
+- Python 3.11
+
+If you do not have one of these versions installed on you machine, we
+recommend that you go to the 
+`Python website <https://www.python.org/downloads/>`_ and
+download the installer for one of these versions. [1]_
+
+A Note for Windows Users
+++++++++++++++++++++++++
+
+  If you are using Windows and are new to Python, we recommend that you
+  still install Python using the installation package available on 
+  the Python website. There are several versions of Python available
+  on the Windows Store, but they can be... finicky, and experience seems
+  to suggest that downloadable available on the Python website produce
+  better results.
+
+  In addition, we recommend that you install the 
+  `Windows Terminal <https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab>`_
+  from the Microsoft Store. It is still possible to use PowerShell or 
+  the Command Prompt, but Windows Terminal tends to be more beginner
+  friendly and allows for a greater range of utility than the natively
+  installed terminal options (for example, it allows for you to install
+  the more recent version of PowerShell, 
+  `PowerShell 7 <https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell>`_,
+  and for the use of the Linux Subsystem for Windows).
+
+
+Setting Up a Virtual Environment
+--------------------------------
+
+Once Python is installed on your system, you will want to open the terminal
+and navigate to the working directory of your project. Here are some brief
+instructions for doing so on different systems:
+
+- **MacOS**: To open the terminal, you will likely want to use the
+  Spotlight Search (the magnifying glass in the top right corner of
+  your screen) to find the "Terminal" application (you can also access
+  Spotlight Search by pressing "Command (⌘) + Space"). Once you have
+  the terminal open, type ``cd`` followed by the path to your working
+  directory. For example, if you are working on a project called
+  ``my_project`` in your ``Documents`` folder, you may access by typing
+  the command
+
+  .. code-block:: console
+
+    cd ~/Documents/my_project
+      
+  into the terminal (here the ``~`` is a shortcut for your home directory).
+  If you do not know what your working directory is, you can find it by
+  navigating to the desired folder in your file explorer, and clicking
+  on "Get Info". The path will be labeled "Where" and from there you
+  can copy the path to your clipboard and paste it in the terminal.
+
+
+- **Linux**: Most Linux distributions have the keyboard shortcut
+  ``Ctrl + Alt + T`` set to open the terminal. From there you may navigate
+  to your working directory by typing ``cd`` followed by the path to your
+  working directory. For example, if you are working on a project called
+  ``my_project`` in your ``Documents`` folder, you may access this via
+  the command
+
+  .. code-block:: console
+
+    cd ~/Documents/my_project
+
+  (here the ``~`` is a shortcut for your home directory). If you do not
+  know what your working directory is, you can find it by navigating to
+  the desired folder in your file explorer, and clicking on "Properties".
+  The path will be labeled "Location" and from there you can copy the path
+  to your clipboard and paste it in the terminal (to paste in the terminal
+  in Linux, you will need to use the keyboard shortcut ``Ctrl + Shift + V``
+  instead of ``Ctrl + V``).
+
+- **Windows**: Open the Windows Terminal and type ``cd`` followed by the
+  path to your working directory. For example, if you are working on a
+  project called ``my_project`` in your ``Documents`` folder, you may
+  access this by typing the command
+
+  .. code-block:: console
+
+    cd ~\Documents\my_project
+
+  into the terminal (here the ``~`` is a shortcut for your home directory). 
+  If you do not know what your working directory is,
+  you can find it by navigating to the desired folder in your file
+  explorer, and clicking on "Properties". The path will be labeled
+  "Location" and from there you can copy the path to your clipboard
+  and paste it in the terminal.
+
+
+Once you have navigated to your working directory, you will want to
+set up a virtual environment. This is a way of isolating the Python
+packages you install for this project from the packages you have
+installed globally on your system. This is useful because it allows
+you to install different versions of packages for different projects
+without worrying about compatibility issues. To set up a virtual
+environment, type the following command into the terminal:
+
+.. code-block:: console
+
+  python -m venv .venv
+
+This will create a virtual environment in your working directory which
+you can see if you list all the files in your working directory via
+the command ``ls -a`` (``dir`` on Windows). Now we need to activate the
+virtual environment. To do this, type the following command into the
+terminal:
+
+- **Windows**: ``.venv\Scripts\activate``
+- **MacOS/Linux**: ``source .venv/bin/activate``
+
+You should now see ``(.venv)`` at the beginning of your terminal prompt
+now. This indicates that you are in the virtual environment, and are now
+ready to install GerryChain.
 
 To install GerryChain from PyPI_, run ``pip install gerrychain`` from
 the command line. 
@@ -78,40 +198,120 @@ adjacencies or reading in shapefiles, then run
 
 This approach sometimes fails due to compatibility issues between our
 different Python GIS dependencies, like ``geopandas``, ``pyproj``,
-``fiona``, and ``shapely``. For this reason, we recommend installing
-from conda-forge for users that encounter difficulty with PyPI_. 
+``fiona``, and ``shapely``. If you run into this issue, try installing
+the dependencies using the `geo_settings.txt <./geo_settings.txt>`_
+file. To do this, run ``pip install -r geo_settings.txt`` from the
+command line.
+
+.. note::
+
+  If you plan on following through the tutorials present within the
+  remainder of this documentation, you will also need to install
+  ``matplotlib`` from PyPI_. This can also be accomplished with
+  a simple invocation of ``pip install matplotlib`` from the command
+  line.
 
 .. _PyPI: https://pypi.org/
+.. [1] Of course, if you are using a Linux system, you will either need to use your
+  system's package manager or install from source. You may also find luck installing
+  Python directly from the package manager if you find installing from source to be
+  troublesome.
 
-Using conda
--------------------------
+Making an Environment Reproducible
+----------------------------------
 
-To install GerryChain from conda-forge_ using conda_, run
+If you are working on a project wherein you would like to ensure
+particular runs are reproducible, it is necessary to invoke
 
-.. code-block:: console
+- **MacOS/Linux**: ``export PYTHONHASHSEED=0``
+- **Windows**: 
 
-    conda install -c conda-forge gerrychain
+  - PowerShell ``$env:PYTHONHASHSEED=0``
+  - Command Prompt ``set PYTHONHASHSEED=0``
 
-For this command to work as intended, you will first need to activate
-the conda environment that you want to install GerryChain in. If
-the environment you want to activate is called ``vrdi`` (for example),
-then you can do this by running
+before running your code. This will ensure that the hash seed is deterministic
+which is important for the replication of spanning trees across your runs. If you
+would prefer to not have to do this every time, then you need to modify the
+activation script for the virtual environment. Again, this is different depending
+on your operating system:
 
-.. code-block:: console
+- **MacOS/Linux**: Open the file ``.venv/bin/activate`` located in your working
+  directory using your favorite text editor
+  and add the line ``export PYTHONHASHSEED=0`` after the ``export PATH`` command. 
+  So you should see something like:: 
 
-    conda activate vrdi
+    _OLD_VIRTUAL_PATH="$PATH"
+    PATH="$VIRTUAL_ENV/Scripts:$PATH"
+    export PATH
 
-If this command causes problems, make sure conda is up-to-date by
-running
+    export PYTHONHASHSEED=0
+
+  Then, verify that the hash seed is set to 0 in your Python environment by
+  running ``python`` from the command line and typing 
+  ``import os; print(os.environ['PYTHONHASHSEED'])``.
 
-.. code-block:: console
+- **Windows**: To be safe, you will need to modify 3 files within your virtual
+  environment:
+
+  - ``.venv\Scripts\activate``: Add the line ``export PYTHONHASHSEED=0`` after
+    the ``export PATH`` command. So you should see something like:: 
+
+      _OLD_VIRTUAL_PATH="$PATH"
+      PATH="$VIRTUAL_ENV/Scripts:$PATH"
+      export PATH
+
+      export PYTHONHASHSEED=0
+
+  - ``.venv\Scripts\activate.bat``: Add the line ``set PYTHONHASHSEED=0`` to the
+    end of the file. So you should see something like::
+
+      if defined _OLD_VIRTUAL_PATH set PATH=%_OLD_VIRTUAL_PATH%
+      if not defined _OLD_VIRTUAL_PATH set _OLD_VIRTUAL_PATH=%PATH%
+
+      set PATH=%VIRTUAL_ENV%\Scripts;%PATH%
+      rem set VIRTUAL_ENV_PROMPT=(.venv) 
+      set PYTHONHASHSEED=0
+
+  - ``.venv\Scripts\Activate.ps1``: Add the line ``$env:PYTHONHASHSEED=0`` to the
+    end of the before the signature block. So you should see something like::
+
+      # Add the venv to the PATH
+      Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH
+      $Env:PATH = "$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH"
+
+      $env:PYTHONHASHSEED=0
+
+      # SIG # Begin signature block
+
+After you have made these changes, verify that the hash seed is set to 0 in your
+Python environment by running ``python`` from the command line and typing 
+``import os; print(os.environ['PYTHONHASHSEED'])`` in the Python prompt.
+
+.. admonition:: A Note on Jupyter
+  :class: note
+
+  If you are using a jupyter notebook, you will need to make sure that you have
+  installed the ``ipykernel`` package in your virtual environment as well as
+  either ``jypyternotebook`` or ``jupyterlab``. To install these packages, run
+  ``pip install <package-name>`` from the command line. Then, to use the virtual
+  python environment in your jupyter notebook, you need to invoke
+
+  .. code-block:: console
+
+    jupyter notebook
+
+  or
+
+  .. code-block:: console
+
+    jupyter lab
 
-    conda update conda
-    conda init
+  from the command line of your working directory *while your virtual environment
+  is activated*. This will open a jupyter notebook in your default browser. You may
+  then check that the hash seed is set to 0 by running the following code in a cell
+  of your notebook:
 
-For more information on using conda to install packages and manage
-dependencies, see `Getting started with conda`_.
+  .. code-block:: python
 
-.. _`Getting started with conda`: https://conda.io/projects/conda/en/latest/user-guide/getting-started.html
-.. _conda: https://conda.io/projects/conda/en/latest/
-.. _conda-forge: https://conda-forge.org/
+    import os
+    print(os.environ['PYTHONHASHSEED'])