climate-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [1/2] git commit: CLIMATE-335 - Add backend documentation to Sphinx build
Date Tue, 01 Apr 2014 02:56:56 GMT
Repository: climate
Updated Branches:
  refs/heads/master c9558e0e1 -> c273e2ed9

CLIMATE-335 - Add backend documentation to Sphinx build

- Add sphinxcontrib.autohttp.bottle extension. The makes endpoint
  documentation really easy and automatic.
- Add documentation explaining the various backend modules.


Branch: refs/heads/master
Commit: adc355cb3a0d98d8172ac79c62d2e7c0adf6170a
Parents: c9558e0
Author: Michael Joyce <>
Authored: Thu Mar 27 17:02:55 2014 -0700
Committer: Michael Joyce <>
Committed: Sat Mar 29 22:08:36 2014 -0700

 docs/source/                |  8 +++-
 docs/source/index.rst              |  1 +
 docs/source/ui-backend/backend.rst | 80 +++++++++++++++++++++++++++++++++
 3 files changed, 88 insertions(+), 1 deletion(-)
diff --git a/docs/source/ b/docs/source/
index 676164b..c1969db 100644
--- a/docs/source/
+++ b/docs/source/
@@ -21,6 +21,7 @@ import sys, os
 # Assuming a fresh checkout of trunk, this will point us to the OCW package
 sys.path.insert(0, os.path.abspath('../../ocw'))
 sys.path.insert(0, os.path.abspath('../../ocw/data_source'))
+sys.path.insert(0, os.path.abspath('../../ocw-ui/backend'))
 # -- General configuration -----------------------------------------------------
@@ -30,7 +31,12 @@ sys.path.insert(0, os.path.abspath('../../ocw/data_source'))
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.ifconfig']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.ifconfig',
+    'sphinxcontrib.autohttp.bottle',
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e37e8a2..f57dd82 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -17,6 +17,7 @@ Contents:
+   ui-backend/backend.rst
 Indices and tables
diff --git a/docs/source/ui-backend/backend.rst b/docs/source/ui-backend/backend.rst
new file mode 100644
index 0000000..f2fe6fb
--- /dev/null
+++ b/docs/source/ui-backend/backend.rst
@@ -0,0 +1,80 @@
+Evaluation UI Webservices
+The OCW evaluation UI is a demonstration web application that is built upon the
+OCW toolkit. The web services for the application are written in Python on top
+of the Bottle Web Framework.
+Configuration and Dependencies
+The Evaluation UI is built on top of the OCW toolkit and as such requires it to
+function properly. Please check the toolkit's documentation for relevant
+installation instructions. You will also need to ensure that you have Bottle
+installed. You can install it with:
+.. code::
+    pip install bottle
+The backend serves the static files for the evaluation frontend as well. If you
+plan to use the frontend you need to ensure that the *app* directory is present
+in the main web service directory. The easiest way to do this is to create a
+symbolic link where the *run_webservices* module is located. Assuming you have
+the entire *ocw-ui* directory, you can do this with the following command.
+.. code::
+    cd ocw-ui/backend
+    ln -s ../frontend/app app
+Finally, to start the backend just run the following command.
+.. code::
+    python
+Web Service Explanation
+The backend endpoints are broken up into a number of modules for ease of
+maintenance and understanding. The *run_webservices* module is the primary
+application module. It brings together all the various submodules into a
+useful system. It also defines a number of helpful endpoints for returning
+static files such as the index page, CSS files, JavaScript files, and more.
+Local File Metadata Extractors
+The *local_file_metadata_extractors* module contains all the endpoints that are
+used to strip information out of various objects for display in the UI. At the
+moment, the main functionality is stripping out metadata from NetCDF files when
+a user wishes to *load* a local file into the evaluation.
+.. autobottle:: local_file_metadata_extractors:lfme_app
+Directory Helpers
+The *directory_helpers* module contains a number of endpoints for working
+directory manipulation. The frontend uses these endpoints to grab directory
+information (within a prefix path for security), return result directory
+information, and other things.
+.. autobottle:: directory_helpers:dir_app
+RCMED Helpers
+The *rcmed_helpers* module contains endpoints for loading datasets from the
+Regional Climate Model Evaluation Database at NASA's Jet Propulsion Laboratory.
+.. autobottle:: rcmed_helpers:rcmed_app
+Processing Endpoints
+The *processing* module contains all the endpoints related to the running of
+.. autobottle:: processing:processing_app

View raw message