Merge commit 'a3356c98134c9e2995207a00c40276587de05bc2' as 'docs/_esnet'

docs/_esnet/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2014, ESnet
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the {organization} nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/_esnet/README.rst

@@ -0,0 +1,107 @@
+esnet-gh-pages-base
+===================
+
+Base templates for ESnet's GitHub pages. These pages are created using the
+Sphinx_ documentation package using the sphinx-bootstrap-theme_ with some
+pages.  This repo is meant to be included into a project using git subtree and
+provides the overrides and customizations to the base theme.
+
+.. _Sphinx: http://sphinx-doc.org
+.. _sphinx-bootstrap-theme: https://github.com/ryan-roemer/sphinx-bootstrap-theme
+
+Installation
+------------
+
+1. Install Sphinx and sphinx-bootstrap-theme. See the instructions below for
+   installing these either using the Mac OS X base system python or MacPorts.
+2. ``cd $PROJECT_ROOT``
+3. ``mkdir docs``
+4. ``git subtree add --prefix docs/_esnet https://github.com/esnet/esnet-gh-pages-base.git master --squash``
+5. ``cd docs``
+6. ``sphinx-quickstart``
+7. ``ln -s ../_esnet/static _static/esnet``
+8. edit ``conf.py`` as described in the next section
+  
+Editing conf.py
+^^^^^^^^^^^^^^^
+
+``sphinx-quickstart`` creates a basic conf.py file, however to use the ESnet
+theme we need to make some changes. Make the following changes to conf.py::
+
+   # add this with the imports at the top of the file
+   import sphinx_bootstrap_theme
+
+   # change templates_path to this
+   templates_path = ['_esnet/templates']
+
+   # add _esnet to exclude_patterns
+   exclude_patterns = ['_build', '_esnet']
+
+   # change html_theme and html_theme_path:
+   html_theme = 'bootstrap'
+   html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+
+   # add html_theme options:
+   html_theme_options = {
+          "navbar_pagenav": False,
+          "nosidebar": False,
+          "navbar_class": "navbar",
+          "navbar_site_name": "Section",
+          "source_link_position": "footer",
+       "navbar_links": [
+           ("Index", "genindex"),
+           ("ESnet", "https://www.es.net", True),
+       ],
+   }
+
+   # add html_logo and html_sidebars
+   html_logo = "_esnet/static/logo-esnet-ball-sm.png"
+   html_sidebars = {'index': None, 'search': None, '*': ['localtoc.html']}
+   html_favicon = "_esnet/static/favicon.ico"
+   html_context = {
+      "github_url": "https://github.com/esnet/PROJNAME",
+   }
+
+That's it!
+
+Sphinx Installation using Mac OS X Base Python
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. sudo /usr/bin/easy_install pip
+2. sudo /usr/local/bin/pip install sphinx sphinx-bootstrap-theme
+
+Sphinx Installation using MacPorts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. port install python27 py27-pip py27-sphinx
+2. port select pip py27-pip
+3. port select sphinx py27-sphinx
+4. pip install sphinx sphinx-bootstrap-theme # make sure this is
+   /opt/local/bin/pip
+
+Creating Content, Previewing and Publishing
+-------------------------------------------
+
+The files are in the ``docs`` directory.  Take a look at the content of
+``index.rst``.  Take a look at the docs from other projects and review the
+documentation for Sphinx_.
+
+Building HTML
+^^^^^^^^^^^^^
+
+In the ``docs`` directory run ``make clean html``.
+
+Previewing the site
+^^^^^^^^^^^^^^^^^^^
+
+``open _build/html/index.html``
+
+or
+
+``open -a /Application/Google\ Chrome.app _build/html/index.html``
+
+Publishing the site
+^^^^^^^^^^^^^^^^^^^
+
+From the ``docs`` directory run ``_esnet/deploy.sh``.  It will be visible at:
+``http://github.com/esnet/PROJECT``.

docs/_esnet/deploy.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+
+GIT_URL=`git remote show origin | awk '/Push  URL/ { print $NF }'`
+DEPLOY_DIR=/tmp/deploy.$$
+mkdir ${DEPLOY_DIR}
+(cd ${DEPLOY_DIR} ; \
+    git clone ${GIT_URL} . \
+ && git checkout gh-pages \
+ && git rm -rf .
+)
+cp -r _build/html/* ${DEPLOY_DIR}
+touch ${DEPLOY_DIR}/.nojekyll
+(cd ${DEPLOY_DIR} ; \
+    git add .nojekyll *  \
+    && git commit -m "deploy"  \
+    && git push)
+
+rm -rf ${DEPLOY_DIR}

docs/_esnet/static/esnet.css

@@ -0,0 +1,84 @@
+body {
+	padding-top: 70px; // bootstrap default
+}
+
+.navbar-default {
+	background-color: #006495;
+	border-color: #004e74;
+}
+.navbar-default .navbar-brand {
+	color: #ecf0f1;
+}
+.navbar-default .navbar-brand:hover, .navbar-default .navbar-brand:focus {
+	color: #ffffff;
+}
+.navbar-default .navbar-text {
+	color: #ecf0f1;
+}
+.navbar-default .navbar-nav > li > a {
+	color: #ecf0f1;
+}
+.navbar-default .navbar-nav > li > a:hover, .navbar-default .navbar-nav > li > a:focus {
+	color: #ffffff;
+}
+.navbar-default .navbar-nav > .active > a, .navbar-default .navbar-nav > .active > a:hover, .navbar-default .navbar-nav > .active > a:focus {
+	color: #ffffff;
+	background-color: #004e74;
+}
+.navbar-default .navbar-nav > .open > a, .navbar-default .navbar-nav > .open > a:hover, .navbar-default .navbar-nav > .open > a:focus {
+	color: #ffffff;
+	background-color: #004e74;
+}
+.navbar-default .navbar-toggle {
+	border-color: #004e74;
+}
+.navbar-default .navbar-toggle:hover, .navbar-default .navbar-toggle:focus {
+	background-color: #004e74;
+}
+.navbar-default .navbar-toggle .icon-bar {
+	background-color: #ecf0f1;
+}
+.navbar-default .navbar-collapse,
+.navbar-default .navbar-form {
+	border-color: #ecf0f1;
+}
+.navbar-default .navbar-link {
+	color: #ecf0f1;
+}
+.navbar-default .navbar-link:hover {
+	color: #ffffff;
+}
+
+@media (max-width: 767px) {
+	.navbar-default .navbar-nav .open .dropdown-menu > li > a {
+		color: #ecf0f1;
+	}
+	.navbar-default .navbar-nav .open .dropdown-menu > li > a:hover, .navbar-default .navbar-nav .open .dropdown-menu > li > a:focus {
+		color: #ffffff;
+	}
+	.navbar-default .navbar-nav .open .dropdown-menu > .active > a, .navbar-default .navbar-nav .open .dropdown-menu > .active > a:hover, .navbar-default .navbar-nav .open .dropdown-menu > .active > a:focus {
+		color: #ffffff;
+		background-color: #004e74;
+	}
+}
+
+/*
+ * Veritcal divider
+ */
+.navbar .divider-vertical {
+    height: 50px;
+    margin: 0 9px;
+    border-right: 1px solid #ecf0f1;
+    border-left: 1px solid #ecf0f1;
+}
+
+.navbar-inverse .divider-vertical {
+    border-right-color: #222222;
+    border-left-color: #111111;
+}
+
+@media (max-width: 767px) {
+    .navbar-collapse .nav > .divider-vertical {
+            display: none;
+    }
+}

docs/_esnet/templates/layout.html

@@ -0,0 +1,134 @@
+{% extends "basic/layout.html" %}
+
+{% set theme_css_files = [] %}
+{% if theme_bootstrap_version == "3" %}
+  {% set bootstrap_version, bootstrap_additional_css, navbar_version = "3.1.0", "theme", "" %}
+  {% set bs_span_prefix = "col-md-" %}
+{% else %}
+  {% set bootstrap_version, bootstrap_additional_css, navbar_version = "2.3.2", "responsive", "-2" %}
+  {% set bs_span_prefix = "span" %}
+{% endif %}
+
+{% set theme_css_files = theme_css_files + [
+    '_static/bootstrap-' + bootstrap_version + '/css/bootstrap.min.css',
+    '_static/bootstrap-sphinx.css',
+    '_static/esnet/esnet.css'
+  ]
+%}
+
+{% if not bootswatch_css_custom %}
+  {% set bootswatch_css_custom = [] %}
+{% endif %}
+{% set css_files = css_files + theme_css_files + bootswatch_css_custom %}
+
+{% set script_files = script_files + [
+    '_static/js/jquery-1.11.0.min.js',
+    '_static/js/jquery-fix.js',
+    '_static/bootstrap-' + bootstrap_version + '/js/bootstrap.min.js',
+    '_static/bootstrap-sphinx.js'
+  ]
+%}
+
+{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and sidebars %}
+{# set render_sidebar = True %}
+{%- set sidebars = ['localtoc.html', 'sourcelink.html', 'searchbox.html'] #}
+{%- set bs_content_width = render_sidebar and "9" or "9"%}
+
+{%- block doctype -%}
+<!DOCTYPE html>
+{%- endblock %}
+
+{# Sidebar: Rework into our Bootstrap nav section. #}
+{% macro navBar() %}
+{% include "navbar" + navbar_version + ".html" %}
+{% endmacro %}
+
+{% if theme_bootstrap_version == "3" %}
+  {%- macro bsidebar() %}
+      {%- if render_sidebar %}
+      <div class="{{ bs_span_prefix }}3">
+        <div id="sidebar" class="bs-sidenav" role="complementary">
+          {%- for sidebartemplate in sidebars %}
+            {%- include sidebartemplate %}
+          {%- endfor %}
+        </div>
+      </div>
+      {%- else %}
+      <div class="{{ bs_span_prefix }}1"></div>
+      {%- endif %}
+  {%- endmacro %}
+{% else %}
+  {%- macro bsidebar() %}
+      {%- if render_sidebar %}
+      <div class="{{ bs_span_prefix }}3">
+        <div id="sidebar" class="bs-sidenav well" data-spy="affix">
+          {%- for sidebartemplate in sidebars %}
+            {%- include sidebartemplate %}
+          {%- endfor %}
+        </div>
+      </div>
+      {%- endif %}
+  {%- endmacro %}
+{% endif %}
+
+{%- block extrahead %}
+<meta charset='utf-8'>
+<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
+<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
+<meta name="apple-mobile-web-app-capable" content="yes">
+{% endblock %}
+
+{# Silence the sidebar's, relbar's #}
+{% block header %}{% endblock %}
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}
+{% block sidebarsourcelink %}{% endblock %}
+
+{%- block content %}
+{{ navBar() }}
+<div class="container">
+  <div class="row">
+    {%- block sidebar1 %}{{ bsidebar() }}{% endblock %}
+    <div class="{{ bs_span_prefix }}{{ bs_content_width }}">
+      {% block body %}{% endblock %}
+    </div>
+    {% block sidebar2 %} {# possible location for sidebar #} {% endblock %}
+  </div>
+</div>
+{%- endblock %}
+
+{%- block footer %}
+<footer class="footer">
+  <div class="container">
+    <div class="row">
+      <div class="col-md-1">
+        <a href="http://www.es.net/"><img src="_static/esnet/logo-esnet.png" alt="[ESnet]"></a>
+      </div>
+      <div class="col-md-11">
+        <p class="pull-right">
+        <a href="#">Back to top</a>
+        {% if theme_source_link_position == "footer" %}
+        <br/>
+        {% include "sourcelink.html" %}
+        {% endif %}
+        </p>
+        <p>
+        {%- if show_copyright %}
+          {%- if hasdoc('copyright') %}
+            {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/>
+          {%- else %}
+            {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}<br/>
+          {%- endif %}
+        {%- endif %}
+        {%- if last_updated %}
+          {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>
+        {%- endif %}
+        {%- if show_sphinx %}
+          {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}<br/>
+        {%- endif %}
+        </p>
+      </div>
+    </div>
+  </div>
+</footer>
+{%- endblock %}

docs/_esnet/templates/navbar.html

@@ -0,0 +1,51 @@
+  <div id="navbar" class="{{ theme_navbar_class }} navbar-default {% if theme_navbar_fixed_top == 'true' -%} navbar-fixed-top{%- endif -%}">
+    <div class="container">
+      <div class="navbar-header">
+        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
+        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+        </button>
+        <a class="navbar-brand" href="{{ pathto(master_doc) }}">
+          {%- block sidebarlogo %}
+          <!-- LOGO: {{ logo }} {{ pathto('_static/' + logo, 1) }} -->
+            
+            {%- if logo %}<img src="{{ pathto('_static/' + logo, 1) }}">{%- endif %}
+          {%- endblock %}
+          {% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%}
+        </a>
+      </div>
+
+        <div class="collapse navbar-collapse nav-collapse">
+          <ul class="nav navbar-nav">
+            {% block navbartoc %}
+              {% include "globaltoc.html" %}
+              {% if theme_navbar_pagenav %}
+                {% include "navbartoc.html" %}
+              {% endif %}
+            {% endblock %}
+            {% if theme_navbar_sidebarrel %}
+              {% block sidebarrel %}
+                {% include "relations.html" %}
+              {% endblock %}
+            {% endif %}
+            <li class="divider-vertical"></li>
+            {% if theme_navbar_links %}
+              {%- for link in theme_navbar_links %}
+                <li><a href="{{ pathto(*link[1:]) }}">{{ link[0] }}</a></li>
+              {%- endfor %}
+            {% endif %}
+            <li><a href="{{ github_url }}"><img src="_static/esnet/icon-github.png" height="20" width="20"></a></li>
+            {% block navbarextra %}
+            {% endblock %}
+            {% if theme_source_link_position == "nav" %}
+              <li class="hidden-sm">{% include "sourcelink.html" %}</li>
+            {% endif %}
+          </ul>
+          {% block navbarsearch %}
+            {% include "navbarsearchbox.html" %}
+          {% endblock %}
+        </div>
+    </div>
+  </div>

docs/_esnet/templates/relations.html

@@ -0,0 +1,21 @@
+{# Switch to icon instead of text in `sm` view size for BS3 only. #}
+{%- if prev %}
+  <li>
+    <a href="{{ prev.link|e }}" title="{{ _('Previous Chapter: ') + prev.title|striptags }}">
+      <span class="glyphicon glyphicon-chevron-left"></span>
+      <span class="hidden-sm">
+        {{ prev.title|striptags|truncate(length=16, killwords=True) }}
+      </span>
+    </a>
+  </li>
+{%- endif %}
+{%- if next %}
+  <li>
+    <a href="{{ next.link|e }}" title="{{ _('Next Chapter: ') + next.title|striptags }}">
+      <span class="hidden-sm">
+        {{ next.title|striptags|truncate(length=16, killwords=True) }}
+      </span>
+      <span class="glyphicon glyphicon-chevron-right"></span>
+    </a>
+  </li>
+{%- endif %}