Merge pull request #51 from bjbford/documentation

Sphinx-apidoc support for jasper_library

.gitignore

@@ -32,5 +32,4 @@ xps_base/XPS_ROACH2_base/system.xmp.updated
 vivado_pid*.str
 
 # ignore docs build directory
-docs/_build/*
-!/docs/_build/html/src/
+docs/_build/

docs/conf.py

@@ -12,10 +12,21 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
+import os
+import sys
+from sphinx.apidoc import main as sphinx_apidoc_main
+# add jasper_library directory to sys.path so autodoc can document its modules.
+jasper_library_path = os.path.join(os.path.abspath(os.path.dirname(os.path.dirname(__file__))), 'jasper_library')
+sys.path.insert(0, jasper_library_path)
+# use sphinx-apidoc to automatically document modules, classes, functions, etc.
+# Code found here: https://github.com/rtfd/readthedocs.org/issues/1139
+def run_apidoc(_):
+    build_modules_dir = os.path.join(os.path.dirname(__file__), 'src', 'jasper_library_modules')
+    ignore_file  = 'conf.py'
+    sphinx_apidoc_main(['-e', '-o',  build_modules_dir, jasper_library_path, ignore_file, '--force'])
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)
 
 # -- Project information -----------------------------------------------------
 

docs/index.rst

@@ -55,25 +55,30 @@ The recommended OS is Ubuntu as it is what the majority of the collaboration are
 | SKARAB      | Ubuntu 14.04/16.04 | R2016b         | Vivado 2016.2 | `Master HEAD <https://github.com/casper-astro/mlib_devel>`__            |
 +-------------+--------------------+----------------+---------------+-------------------------------------------------------------------------+
 
-1. :doc:`Setting up the toolflow <src/Setting-up-the-tools>`
+1. :doc:`Setting up the Toolflow <src/Setting-up-the-Toolflow>`
 2. :doc:`Installing Matlab <src/How-to-install-Matlab>`
 3. :doc:`Installing Xilinx Vivado <src/How-to-install-Xilinx-Vivado>` or :doc:`Installing Xilinx ISE (ROACH only) <src/How-to-install-Xilinx-ISE>`
+4. :doc:`Configuring the Toolflow <src/Configuring-the-Toolflow>`
+5. :doc:`Running the Toolflow <src/Running-the-Toolflow>`
 
 ..  toctree::
     :hidden:
     :maxdepth: 1
     :caption: Setup
 
-    src/Setting-up-the-tools
+    src/Setting-up-the-Toolflow
     src/How-to-install-Matlab
     src/How-to-install-Xilinx-Vivado
     src/How-to-install-Xilinx-ISE
+    src/Configuring-the-Toolflow
+    src/Running-the-Toolflow
 
 Documentation
 ---------------
 
 * `CASPER Tutorials <http://casper-tutorials.readthedocs.io/en/latest/>`__
 * :doc:`Block Documentation <blockdocumentation>`
+* :doc:`JASPER Toolflow <src/jasper_library_modules/modules>`
 
 ..  toctree::
     :hidden:
@@ -82,3 +87,4 @@ Documentation
 
     CASPER Tutorials <http://casper-tutorials.readthedocs.io/en/latest/>
     blockdocumentation
+    src/jasper_library_modules/modules

docs/src/Configuring-the-Toolflow.md

@@ -0,0 +1,48 @@
+# Configuring the Toolflow
+
+It is now time to setup the Xilinx, Matlab and work paths to suit your directory setup. This tells the toolflow where you have installed MATLAB and Xilinx tools, so that it can find and run them. The configuration will depend on the options you selected when you installed these tools.
+
+The design entry portion of the CASPER tool flow consists of MATLAB, Simulink,and System Generator.  The build portion of the CASPER tool flow is done using Xilinx Platform Studio (XPS) or Vivado, depending on the target hardware.  All of these tools require various environment variables to be set.  The `startsg` script will handle all the requisite setup details.
+
+## The `startsg` script
+
+The `startsg` script operates in two different modes, depending on how it is invoked.  When executed as a script it will setup the environment suitably and then launch Matlab (for design entry).  When "sourced" using the bash `source` command, it will setup the environment of the current shell to allow command line use of the Xilinx tools and various CASPER scripts.
+
+    # Running startsg to start Matlab
+    $ /path/to/mlib_devel/startsg
+
+    # Sourcing startsg to setup for command line tools
+    # and then running exec_flow.py from the command line
+    $ source /path/to/mlib_devel/startsg
+    $ /path/to/mlib_devel/jasper_library/exec_flow.py ...
+
+
+## Specifying local details
+
+The `startsg` script is generic.  It does not require that the Matlab and Xilinx tools be installed in specific locations, but it does require that you provide it with a few details about your local installation.  This is done by creating a `startsg.local` file that defines a few key variables from which the other environment variables can be derived.  The two absolutely essential variables are `MATLAB_PATH` and `XILINX_PATH`.  Another variable that can be defined is `PLATFORM`, which is used by the Xilinx tools to select suitable runtime binaries for your system.  If not specified, it will be defaulted to `lin64` which (as of this writing) is the most commonly used platform for CASPER development and a warning message will be issued.  Other variables that you may wish to define in `startsg.local` are `XILINXD_LICENSE_FILE` to point to your Xilinx software license if it exists in a non-standard location and `JASPER_BACKEND` to specify which Xilinx tools will be used to implement your design (currently supported options are `vivado` or `ise`, with `vivado` being the default).
+
+Here is a sample `startsg.local` file:
+
+    export XILINX_PATH=/opt/Xilinx/Vivado/2016.4
+    export MATLAB_PATH=/usr/local/MATLAB/R2016b
+    export PLATFORM=lin64
+    export JASPER_BACKEND=vivado
+
+## Other features
+
+### Symlink for convenience
+
+Running `startsg` from the `mlib_devel` directory (where it lives) will start Matlab with `mlib_devel` as the current directory.  This requires that you navigate within Matlab to the directory where your model file lives.  To avoid this minor annoyance, you can create a symbolic link to `startsg` in your application directory (i.e.  where your model file lives).  When running `startsg` via this symlink, Matlab will start up with your application directory as the current directory and also run the optional `casper_startup.m` file if one exists.
+
+### Symlinks for multiple tool versions
+
+If you have multiple versions of the Matlab or Xilinx tools, you can create different `startsg.local` files for the different versions.  For example, you might have `startsg-2016-1.local` that points to the 2016.1 version of the Xilinx tools and `startsg-2016-4.local` that points to the 2016.4 version.  To utilize these version specific `.local` files, you can either pass them on the command line to `startsg` or you can create symlinks with version specific names that match the base name of the version specific local file.  Here are some examples that show how this works:
+
+    $ startsg                       # Uses startsg.local
+
+    $ startsg startsg-2016-1.local  # Uses startsg-2016-1.local
+
+    $ ln -s /path/to/mlib_devel/startsg startsg-2016-1
+    $ ./startsg-2016-1              # Uses startsg-2016-1.local
+
+Now copy 'startsg.local.example' to 'startsg.local' and add the correct path to the following parameters in 'startsg.local': `XILINX_PATH` (path to your Xilinx script), `MATLAB_PATH` (path to your Matlab script), `PLATFORM` (this is set to `lin64` for a 64 bit Linux system) and `JASPER_BACKEND` (this is set to `vivado` by default, but can also be `ise`). Remember to save the file. NB: Please do not commit or push these file changes to the git repo, as this file will constantly change from one user to the next. In fact, the repository has been explicitly configured to ignore changes to the `startsg.local` file -- you shouldn't change this behaviour!

docs/src/Setting-up-the-tools.md → docs/src/Running-the-Toolflow.md

@@ -1,45 +1,4 @@
-# Setting up the toolflow
-
-This page explains how to install the CASPER tools and what supporting software is required to run them.
-
-## Getting the right tools for your hardware
-The CASPER tools have changed significantly to support Xilinx series 7 (and later) FPGAs. For these boards -- i.e. any FPGA platform based on a 7-series, UltraScale, or Ultrascale+ board -- you should follow the latest instructions in this guide for the _Vivado-based_ flow.
-For earlier platforms, which include ROACH1 and ROACH2, you should follow instructions for the _ISE-based_ flow.
-
-## Required 3rd Party Tools
-
-**Operating System**
-We suggest Ubuntu 14.04 LTS, Ubuntu 16.04 LTS (with tweaks to the system) or Red Hat Enterprise 6.6 (Santiago). Other operating systems are viable, but proceed at your own risk!
-
-**MATLAB**
-The tools currently support MATLAB 2016b, and the corresponding version of Simulink. You will need to obtain this software, and corresponding licenses either direct from MathWorks or from your institution. For MATLAB install instructions, refer to [How to install Matlab.](How-to-install-Matlab.html)
-
-**Xilinx ISE/Vivado**
-For _Vivado-based_ flows, you need to install Xilinx Vivado. Currently we support version 2016.4. These are available from <xilinx.com> and will require a license. If you are part of an academic institution, you may be eligible for free licenses via the [Xilinx University Program](https://www.xilinx.com/support/university.html). For Xilinx ISE or Vivado install instructions, refer to [How to install Xilinx ISE](How-to-install-Xilinx-ISE.html) or [How to install Xilinx Vivado.](How-to-install-Xilinx-Vivado.html)
-
-For _ISE-based_ flows, you need to install Xilinx ISE 14.7. Again, this is available from <xilinx.com>, and academic institutions may be eligible for free licenses via the [Xilinx University Program](https://www.xilinx.com/support/university.html).
-
-**Python**
-The toolflow requires Python 2.7. If you don't have it already you can install it in Ubuntu environments by opening a terminal <ctrl +alt + T> and running the command `sudo apt-get install python`.
-
-You'll also need the [PyYAML](https://pypi.python.org/pypi/PyYAML) package. You can download this and install this directly from source, or use a Python package manager, for example, [pip](https://pypi.python.org/pypi/pip). To install pip, from a terminal, run `sudo apt-get install python-pip`.
-
-Once you have pip installed, you can install pyyaml by running the command `sudo pip install pyyaml` in a terminal.
-
-## Obtaining the Toolflow
-
-The CASPER toolflow resides in this repository. You can download a copy of it to your local machine with the command `git clone https://github.com/casper-astro/mlib_devel.git`. This will leave you on the master branch. If you wish to select another branch (for example, the `roach2` branch) you can do this by first going in to the newly-cloned repository (`cd mlib_devel`) and then switching branches with `git checkout -b roach2 origin/roach2`. You can always see what remote branches are available (i.e., which branches are in the casper-astro github repository) by running `git branch -r` in your local "mlib_devel" folder.
-
-Using the terminal, type the following:
-`git status` in the "mlib_devel" folder. 
-This should indicate that the master branch has been selected.
-
-## Configuring the Toolflow
-
-It is now time to setup the Xilinx, Matlab and work paths to suit your directory setup. This tells the toolflow where you have installed MATLAB and Xilinx tools, so that it can find and run them. The configuration will depend on the options you selected when you installed these tools.
-Using the terminal, go to the "mlib_devel" directory and read the `README.startsg` file, which will explain what 'startsg' and 'startsg.local' does and how to set it up. Now copy 'startsg.local.example' to 'startsg.local' and add the correct path to the following parameters in 'startsg.local': `XILINX_PATH` (path to your Xilinx script), `MATLAB_PATH` (path to your Matlab script), `PLATFORM` (this is set to `lin64` for a 64 bit Linux system) and `JASPER_BACKEND` (this is set to `vivado` by default, but can also be `ise`). Remember to save the file. NB: Please do not commit or push these file changes to the git repo, as this file will constantly change from one user to the next. In fact, the repository has been explicitly configured to ignore changes to the `startsg.local` file -- you shouldn't change this behaviour!
-
-## Running the Toolflow
+# Running the Toolflow
 
 1) There are two ways of working with the [new, Vivado-based] CASPER toolflow. You can do this initially with the MATLAB GUI to compile the front end and then handle the middleware and backend generation using Python or you can run everything in Python. The former stage is more for design and debugging (steps 2-11) and the later stage (steps 12-15) is for the final tested and working design. This How To will cover both methods.
 

docs/src/Setting-up-the-Toolflow.md

@@ -0,0 +1,33 @@
+# Setting up the Toolflow
+
+This page explains how to install the CASPER tools and what supporting software is required to run them.
+
+## Obtaining the Toolflow
+
+The CASPER toolflow resides in this repository. You can download a copy of it to your local machine with the command `git clone https://github.com/casper-astro/mlib_devel.git`. This will leave you on the master branch. If you wish to select another branch (for example, the `roach2` branch) you can do this by first going in to the newly-cloned repository (`cd mlib_devel`) and then switching branches with `git checkout -b roach2 origin/roach2`. You can always see what remote branches are available (i.e., which branches are in the casper-astro github repository) by running `git branch -r` in your local "mlib_devel" folder.
+
+Using the terminal, type the following: `git status` in the "mlib_devel" folder. This should indicate that the master branch has been selected.
+
+## Getting the right tools for your hardware
+The CASPER tools have changed significantly to support Xilinx series 7 (and later) FPGAs. For these boards -- i.e. any FPGA platform based on a 7-series, UltraScale, or Ultrascale+ board -- you should follow the latest instructions in this guide for the _Vivado-based_ flow.
+For earlier platforms, which include ROACH1 and ROACH2, you should follow instructions for the _ISE-based_ flow.
+
+## Required 3rd Party Tools
+
+**Operating System**
+We suggest Ubuntu 14.04 LTS, Ubuntu 16.04 LTS (with tweaks to the system) or Red Hat Enterprise 6.6 (Santiago). Other operating systems are viable, but proceed at your own risk!
+
+**Python**
+The toolflow requires Python 2.7. If you don't have it already you can install it in Ubuntu environments by opening a terminal <ctrl +alt + T> and running the command `sudo apt-get install python`.
+
+You'll also need the [PyYAML](https://pypi.python.org/pypi/PyYAML) package. You can download this and install this directly from source, or use a Python package manager, for example, [pip](https://pypi.python.org/pypi/pip). To install pip, from a terminal, run `sudo apt-get install python-pip`.
+
+Once you have pip installed, you can install pyyaml by running the command `sudo pip install pyyaml` in a terminal.
+
+**MATLAB**
+The tools currently support MATLAB 2016b, and the corresponding version of Simulink. You will need to obtain this software, and corresponding licenses either direct from MathWorks or from your institution. For MATLAB install instructions, refer to [How to install Matlab.](How-to-install-Matlab.html)
+
+**Xilinx ISE/Vivado**
+For _Vivado-based_ flows, you need to install Xilinx Vivado. Currently we support version 2016.4. These are available from <xilinx.com> and will require a license. If you are part of an academic institution, you may be eligible for free licenses via the [Xilinx University Program](https://www.xilinx.com/support/university.html). For Xilinx ISE or Vivado install instructions, refer to [How to install Xilinx ISE](How-to-install-Xilinx-ISE.html) or [How to install Xilinx Vivado.](How-to-install-Xilinx-Vivado.html)
+
+For _ISE-based_ flows, you need to install Xilinx ISE 14.7. Again, this is available from <xilinx.com>, and academic institutions may be eligible for free licenses via the [Xilinx University Program](https://www.xilinx.com/support/university.html).

docs/src/jasper_library_modules/castro.rst

@@ -0,0 +1,7 @@
+castro module
+=============
+
+.. automodule:: castro
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/clk_factors.rst

@@ -0,0 +1,7 @@
+clk\_factors module
+===================
+
+.. automodule:: clk_factors
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/constraints.rst

@@ -0,0 +1,7 @@
+constraints module
+==================
+
+.. automodule:: constraints
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/exec_flow.rst

@@ -0,0 +1,7 @@
+exec\_flow module
+=================
+
+.. automodule:: exec_flow
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/helpers.rst

@@ -0,0 +1,7 @@
+helpers module
+==============
+
+.. automodule:: helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/memory.rst

@@ -0,0 +1,7 @@
+memory module
+=============
+
+.. automodule:: memory
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/modules.rst

@@ -0,0 +1,16 @@
+jasper_library
+==============
+
+.. toctree::
+   :maxdepth: 4
+
+   castro
+   clk_factors
+   constraints
+   exec_flow
+   helpers
+   memory
+   platform
+   toolflow
+   verilog
+   yellow_blocks

docs/src/jasper_library_modules/platform.rst

@@ -0,0 +1,7 @@
+platform module
+===============
+
+.. automodule:: platform
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/toolflow.rst

@@ -0,0 +1,7 @@
+toolflow module
+===============
+
+.. automodule:: toolflow
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/jasper_library_modules/verilog.rst

@@ -0,0 +1,7 @@
+verilog module
+==============
+
+.. automodule:: verilog
+    :members:
+    :undoc-members:
+    :show-inheritance: