doc: Update contributing

doc/source/contributing.rst

@@ -82,8 +82,9 @@ Continuous integration (CI) testing will fail if the changes are not pep8 compli
     black /path/to/opencsp -C -S
 
 
-NOTE, the following pre-commit hook can be added to automatically apply black to your
-commits:
+.. note::
+    The following pre-commit hook can be added to automatically apply black to your
+    commits:
 
 ::
 
@@ -99,6 +100,55 @@ commits:
 Getting Started
 ---------------
 
+OpenCSP provides both a library and stand-alone applications that can be used for modeling concentrating solar-thermal power technologies. Lets briefly take a look at the directories within the OpenCSP code base.
+
+Directory Summary
++++++++++++++++++
+
+- *opencsp/app*: OpenCSP library and applications
+- *opencsp/common*: Common code used by the library and applications
+- *doc*: developer documentation
+- *example*: OpenCSP examples
+- *contrib*: Contributed code that is not actively tested or maintained
+
+opencsp/app
++++++++++++
+This directory contains the OpenCSP library and application code.
+
+opencsp/app/camera_calibration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Graphical User Interface which aides in the calibration of machine vision cameras.
+
+opencsp/app/scene_reconstruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Reconstructs a 3d scene of Aruco markers using a calibrated camera.
+
+opencsp/app/select_image_points
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A Graphical User Interface that allows the user to select points on an image. Results are saved to text file.
+
+opencsp/app/sofast
+^^^^^^^^^^^^^^^^^^
+High-precision deflectometry measurement of CSP mirrors, including heliostat facets, full heliostats, and dishes.
+
+opencsp/app/target
+^^^^^^^^^^^^^^^^^^
+Generation and interpretation of optical targets.
+
+
+opencsp/common
+++++++++++++++
+This directory contains the OpenCSP common data and code used by the library and applications above.
+
+opencsp/common/data
+^^^^^^^^^^^^^^^^^^^
+This directoy contains common data used for testing and running examples.
+
+opencsp/common/lib
+^^^^^^^^^^^^^^^^^^
+This directory contains common code and data structures used by the library and application code above. For example, classes to represent light sources, facets, mirrors, and heliostats reside here.
+
+
 Setting up your development environment
 +++++++++++++++++++++++++++++++++++++++
 
@@ -116,28 +166,80 @@ How to install OpenCSP's dependencies
 
 With python version 3.10 or greater, run the following:
 
+Linux
+^^^^^
+
 ::  
 
     $ cd /path/to/OpenCSP/../
-    $ python -m venv ./venv_opencsp
-    # On Linux:
-    $ . ./venv_opencsp/bin/activate
-    # Or, on Windows:
-    $ . ./venv_opencsp/Scripts/activate
-    $ (venv_opencsp) cd OpenCSP
-    $ (venv_opencsp) pip install -r requirements.txt
+    $ python -m venv ./venv
+    # On Linux or MacOS:
+    $ . ./venv/bin/activate
+    $ (venv) cd OpenCSP
+    $ (venv) pip install -r requirements.txt
+
+
+Windows
+^^^^^^^
+
+::
+
+    $ cd \path\to\OpenCSP\..\
+    $ python -m venv .\venv
+    $ . .\venv\Scripts\activate
+    $ (venv) cd OpenCSP
+    $ (venv) pip install -r requirements.txt
+
+
+MacOS
+^^^^^
+
+.. warning::
+    MacOS is not fully supported by OpenCSP.
+
+rawpy may be available via pip install, however, if you are on a M1, M2, or M3 Mac, you may need to install rawpy from source. In order to install rawpy from source, we recommend using the brew package manager. In fact, ffmpeg can be installed with brew as well.
+
+Attempt to install the OpenCSP requirements:
+
+::
+
+    $ cd /path/to/OpenCSP/../
+    $ python -m venv ./venv
+    $ . ./venv/bin/activate
+    $ (venv) cd OpenCSP
+    $ (venv) pip install -r requirements.txt
+
+If rawpy is not available, you can install it from source as follows:
+
+1. Install brew. Please see https://brew.sh.
+2. Install rawpy from source:
+
+::  
+
+    $ brew install [email protected] libomp llvm
+    $ git clone [email protected]:letmaik/rawpy.git
+    $ cd rawpy
+    $ pip install wheel numpy cython
+    $ pip install .
+
+3. Comment out the 'rawpy' line in requirements.txt and then run:
+
+::
+
+    $ (venv) cd OpenCSP
+    $ (venv) pip install -r requirements.txt
 
 Running OpenCSP's test suite
 ++++++++++++++++++++++++++++
 
-Within venv_opencsp, you can now run:
+Within venv, you can now run:
 
 ::
 
-    $ (venv_opencsp) cd /path/to/OpenCSP
-    $ (venv_opencsp) export PYTHONPATH=$PWD
-    $ (venv_opencsp) cd opencsp
-    $ (venv_opencsp) pytest
+    $ (venv) cd /path/to/OpenCSP
+    $ (venv) export PYTHONPATH=$PWD
+    $ (venv) cd opencsp
+    $ (venv) pytest
 
 
 Testing
@@ -253,9 +355,14 @@ Working with remotes
 Now that you have a fork of OpenCSP cloned, you have a single remote named `origin`. This remote
 refers to your fork on GitHub: https://github.com/<github-username>/OpenCSP. This fork contains
 the same branches that the upstream repository at https://github.com/sandialabs/OpenCSP contained
-when it was forked. Note that the branches only reflect the state of the upstream repository at 
-the time it was forked. In order to create a new topic branch with the latest changes from upstream, 
-you must use multiple remotes. To create a upstream remote:
+when it was forked. 
+
+.. note::
+    The branches only reflect the state of the upstream repository at the time it was forked. 
+    In order to create a new topic branch with the latest changes from upstream, you must use 
+    multiple remotes.
+
+To create a upstream remote:
 ::
 
     cd /path/to/OpenCSP
@@ -306,4 +413,5 @@ the PR, consider filing a follow-on issue.
 
 Release Process
 ---------------
-TODO
+Stable releases are tagged on the `main` branch. The tip of the `main` branch is the latest stable release.
+The `develop` branch will contain the latest unreleased changes and should be used with caution.