commit a3356c98134c9e2995207a00c40276587de05bc2 Author: Bruce A. Mah Date: Fri Mar 28 14:55:12 2014 -0700 Squashed 'docs/_esnet/' content from commit c02bf57 git-subtree-dir: docs/_esnet git-subtree-split: c02bf57d43dbfcd7c727cdd17c54f0a480279f9a diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ea4c32f --- /dev/null +++ b/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. \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..0b47098 --- /dev/null +++ b/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``. diff --git a/deploy.sh b/deploy.sh new file mode 100755 index 0000000..223718c --- /dev/null +++ b/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} diff --git a/static/esnet.css b/static/esnet.css new file mode 100644 index 0000000..b84fe91 --- /dev/null +++ b/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; + } +} diff --git a/static/favicon.ico b/static/favicon.ico new file mode 100644 index 0000000..44e5ab2 Binary files /dev/null and b/static/favicon.ico differ diff --git a/static/icon-github.png b/static/icon-github.png new file mode 100755 index 0000000..a9c6940 Binary files /dev/null and b/static/icon-github.png differ diff --git a/static/logo-esnet-ball-sm.png b/static/logo-esnet-ball-sm.png new file mode 100644 index 0000000..16db9f1 Binary files /dev/null and b/static/logo-esnet-ball-sm.png differ diff --git a/static/logo-esnet-ball.png b/static/logo-esnet-ball.png new file mode 100644 index 0000000..16db9f1 Binary files /dev/null and b/static/logo-esnet-ball.png differ diff --git a/static/logo-esnet-name.png b/static/logo-esnet-name.png new file mode 100644 index 0000000..f9ec806 Binary files /dev/null and b/static/logo-esnet-name.png differ diff --git a/static/logo-esnet.png b/static/logo-esnet.png new file mode 100644 index 0000000..78b2497 Binary files /dev/null and b/static/logo-esnet.png differ diff --git a/templates/layout.html b/templates/layout.html new file mode 100644 index 0000000..f43cb44 --- /dev/null +++ b/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 -%} + +{%- 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 %} +
+ +
+ {%- else %} +
+ {%- endif %} + {%- endmacro %} +{% else %} + {%- macro bsidebar() %} + {%- if render_sidebar %} +
+ +
+ {%- endif %} + {%- endmacro %} +{% endif %} + +{%- block extrahead %} + + + + +{% endblock %} + +{# Silence the sidebar's, relbar's #} +{% block header %}{% endblock %} +{% block relbar1 %}{% endblock %} +{% block relbar2 %}{% endblock %} +{% block sidebarsourcelink %}{% endblock %} + +{%- block content %} +{{ navBar() }} +
+
+ {%- block sidebar1 %}{{ bsidebar() }}{% endblock %} +
+ {% block body %}{% endblock %} +
+ {% block sidebar2 %} {# possible location for sidebar #} {% endblock %} +
+
+{%- endblock %} + +{%- block footer %} + +{%- endblock %} diff --git a/templates/navbar.html b/templates/navbar.html new file mode 100644 index 0000000..623faf1 --- /dev/null +++ b/templates/navbar.html @@ -0,0 +1,51 @@ +
+
+
+ + + + {%- block sidebarlogo %} + + + {%- if logo %}{%- endif %} + {%- endblock %} + {% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%} + +
+ +
+
    + {% 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 %} +
  • + {% if theme_navbar_links %} + {%- for link in theme_navbar_links %} +
  • {{ link[0] }}
    • + {%- endfor %} + {% endif %} +
    • + {% block navbarextra %} + {% endblock %} + {% if theme_source_link_position == "nav" %} + + {% endif %} +
+ {% block navbarsearch %} + {% include "navbarsearchbox.html" %} + {% endblock %} +
+
+
diff --git a/templates/relations.html b/templates/relations.html new file mode 100644 index 0000000..e85b69c --- /dev/null +++ b/templates/relations.html @@ -0,0 +1,21 @@ +{# Switch to icon instead of text in `sm` view size for BS3 only. #} +{%- if prev %} +
  • + + + + +
    • +{%- endif %} +{%- if next %} +
  • + + + + +
    • +{%- endif %}