1 files changed, 107 insertions, 0 deletions
diff --git a/docs/_esnet/README.rst b/docs/_esnet/README.rst
new file mode 100644
index 0000000..0b47098
--- /dev/null
+++ b/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``.