Merge pull request #142 from moragb96/docs_update

docs update: updated virtual env creation

docs/index.rst

@@ -94,8 +94,9 @@ Setup Links
 1. :doc:`Installing the Toolflow <src/Installing-the-Toolflow>`
 2. :doc:`Installing Matlab <src/How-to-install-Matlab>`
 3. :doc:`Installing Xilinx Vivado <src/How-to-install-Xilinx-Vivado>`
-4. :doc:`Configuring the Toolflow <src/Configuring-the-Toolflow>`
-5. :doc:`Running the Toolflow <src/Running-the-Toolflow>`
+4. :doc:`Installing casperfpga <src/How-to-install-casperfpga>`
+5. :doc:`Configuring the Toolflow <src/Configuring-the-Toolflow>`
+6. :doc:`Running the Toolflow <src/Running-the-Toolflow>`
 
 ..  toctree::
     :hidden:
@@ -105,6 +106,7 @@ Setup Links
     src/Installing-the-Toolflow
     src/How-to-install-Matlab
     src/How-to-install-Xilinx-Vivado
+    src/How-to-install-casperfpga
     src/Configuring-the-Toolflow
     src/Running-the-Toolflow
 

docs/src/How-to-install-casperfpga.md

@@ -0,0 +1,76 @@
+# How to install casperfpga
+
+This section explains how to install `casperfpga`, a python library used to interact with CASPER hardware.
+
+Once you have cloned the casperfpga repository, ensure that you are on the correct branch (usually **master** unless you are a contributor) and always pull regularly to make sure you have the latest version of casperfpga.
+
+## Installing casperfpga
+
+[`casperfpga`](https://pypi.org/project/casperfpga/) is now available on the Python Package Index (PyPI) and can be installed via [`pip`](https://pip.pypa.io/en/stable/). However, should you need to interface with a SNAP board, your installation workflow involves the extra step of installing against `casperfpga's requirements.txt`.
+
+```shell
+$ git clone https://github.com/casper-astro/casperfpga
+$ cd casperfpga/
+$ git checkout master
+$ sudo apt-get install python-pip
+$ sudo pip install -r requirements.txt
+$ sudo pip install casperfpga
+```
+
+The distribution on the Python Package Index is, of course, a built-distribution; this contains an already-compiled version of the SKARAB programming utility `progska`, written in `C`. Operating Systems tested using `pip install casperfpga` include:
+
+1. Ubuntu 14.04 LTS
+2. Ubuntu 16.04 LTS
+3. Ubuntu 18.04 LTS
+4. Debian 8.x
+
+Unfortunately the success of your installation using `pip` depends on the host OS of the installation, and you might need to rebuild the utility using the C-compiler native to your OS. In short follow the more traditional method of installing custom Python packages.
+
+```shell
+# remove current casperfpga install files
+$ cd /usr/local/lib/python2.7/dist-packages
+$ sudo rm -rf casper*
+
+# clone the repository to your working directory
+$ cd /path/to/working/directory 
+$ git clone https://github.com/casper-astro/casperfpga.git
+$ cd casperfpga
+$ git checkout master
+$ sudo pip install -r requirements.txt
+$ sudo python setup.py install
+```
+
+
+### Testing that the installation worked
+
+To check that casperfpga has been installed correctly open an ipython session and import casperfpga. To avoid errors, move out of your cloned casperfpga repository directory before doing this test. `casperfpga.__version__` will output the build and githash version of your casperfpga library.
+
+```shell
+$ cd ..
+$ ipython
+```
+```python
+In [1]: import casperfpga
+In [2]: casperfpga.__version__
+```
+
+If you receive any errors during this step please feel free to contact anyone on the [CASPER Mailing List](mailto:casper@lists.berkeley.edu), or check the [Mailing List Archive](http://www.mail-archive.com/casper@lists.berkeley.edu/) to see if your issue has been resolved already.
+
+## Using casperfpga
+
+The introductory [tutorials](https://casper-toolflow.readthedocs.io/projects/tutorials/en/latest/) for current CASPER hardware serve as a guide to the entire process of:
+* Creating an FPGA design in Simulink using the CASPER and Xilinx Blocksets
+* Building the design using the toolflow, and lastly
+* Reconfiguring your CASPER Hardware with the generated .fpg file using `casperfpga`
+
+`casperfpga` is written in python and mainly used to communicate with CASPER Hardware and reconfigure it's firmware. Hence the medium of communication is usually done through an ipython session, as shown below:
+
+```python
+import casperfpga
+fpga = casperfpga.CasperFpga('skarab_host or roach_name')
+fpga.upload_to_ram_and_program('your_file.fpg')
+```
+
+## Contributing towards casperfpga
+
+If you would like to contribute towards this library, fork the casperfpga [repo](https://github.com/casper-astro/casperfpga), add your changes to the fork and issue a pull request to the parent repo. 

docs/src/Installing-the-Toolflow.md

@@ -44,17 +44,22 @@ The master branch is usually updated once a year. Between updates, code with new
     To create a Python 3 virtual environment:
 
     ```bash
+    # install the python3-venv package
+    sudo apt install python3-venv
     # change directory to where you want the virtual environment to live
     cd /home/user/work
-    # install virtualenv using pip3
-    sudo pip3 install virtualenv
     # create a Python 3 virtual environment
-    virtualenv -p python3 casper_venv
+    python3 -m venv casper_venv
     # to activate the virtual environment:
     source casper_venv/bin/activate
     # to deactivate the virtual environment:
     deactivate
     ```
+4. casperfpga
+
+    `casperfpga` is a python library used to interact and interface with [**CASPER** Hardware](https://github.com/casper-astro/casper-hardware). Functionality includes being able to reconfigure firmware, as well as read and write registers across the various communication interfaces.
+
+    You will need to install this library to interface with CASPER hardware. Installation instructions can be found [here](https://casper-toolflow.readthedocs.io/en/latest/src/How-to-install-casperfpga.html).
 
 ## Obtaining the Toolflow
 Clone the toolflow from the [mlib_devel](https://github.com/casper-astro/mlib_devel) git repository.