Documentation and website on gh-pages (#2)

* Initialized conf.py to docs website
* Increased timeout for notebook doc building
* Moved landsat example notebook to examples/topics
* Added topics/index.rst
* Added index.rst
* Added README, FAQ, About and index pages for the guides
* Updated landsat spectral clustering notebook to use datashader
* Updated index.rst to link to new notebooks
* Added EarthML wordmark SVG, icon and favicon
* Added .gitignore
* Added user_guide/index.rst
* Added five user guide notebooks

.gitignore

@@ -0,0 +1,108 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+*~
+
+earthml/.version
+.doit*
+
+.DS_Store

doc/FAQ.rst

@@ -0,0 +1,6 @@
+***
+FAQ
+***
+
+Questions we have been asked by users, plus potential pitfalls we hope
+to help users avoid:

doc/README.md

@@ -0,0 +1,2 @@
+Site is built with nbsite; see https://pyviz.github.io/nbsite for
+details and instructions.

doc/Reference_Manual/index.rst

@@ -0,0 +1,7 @@
+****************
+Reference Manual
+****************
+
+To learn how to use Project, we recommend the `Getting Started
+Guide`_, followed by the online help features (e.g. tab complete in
+the Notebook), along with the `User Guide`_.

doc/about.rst

@@ -0,0 +1,4 @@
+About Us
+========
+
+Project is supported and maintained by `Anaconda <https://www.anaconda.com>`_.

doc/conf.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+
+from nbsite.shared_conf import *
+
+###################################################
+# edit things below as appropriate for your project
+
+project = u'EarthML'
+authors = u'Anaconda'
+copyright = u'2018 ' + authors
+description = 'Python tools for earth science and machine learning'
+
+version = '0.0.1'
+release = '0.0.1'
+
+nbbuild_cell_timeout = 10000
+
+html_static_path += ['_static']
+html_theme = 'sphinx_ioam_theme'
+# logo file etc should be in html_static_path, e.g. _static
+
+
+html_theme_options = {
+    'logo':'logo.png',
+    'favicon':'favicon.ico'
+}
+
+_NAV =  (
+    ('Getting Started', 'getting_started/index'),
+    ('User Guide', 'user_guide/index'),
+    ('Gallery', 'gallery/index'),
+    ('API', 'Reference_Manual/index'),
+    ('FAQ', 'FAQ'),
+    ('About', 'about')
+)
+
+html_context.update({
+    'PROJECT': project,
+    'DESCRIPTION': description,
+    'AUTHOR': authors,
+    # will work without this - for canonical (so can ignore when building locally or test deploying)
+    'WEBSITE_SERVER': 'https://pyviz-topics.github.io/EarthML/',
+    'VERSION': version,
+    'NAV': _NAV,
+    # by default, footer links are same as those in header
+    'LINKS': _NAV,
+    'SOCIAL': (
+        ('Github', '//github.com/pyviz-topics/EarthML'),
+    )
+})

doc/getting_started/index.rst

@@ -0,0 +1,10 @@
+***************
+Getting Started
+***************
+
+This 'Getting Started' guide aims to get you using Project
+productively as quickly as possible.
+
+Detailed documentation is contained in the `User Guide
+<../user_guide/index.html>`_; we link to the user guide from the
+appropriate sections of this guide.

doc/index.rst

@@ -0,0 +1,51 @@
+*******
+EarthML
+*******
+
+.. raw:: html
+
+   <div style="width: 65%; float:left">
+
+
+**Machine learning and visualization in Python for Earth science**
+
+EarthML is an `open-source
+<https://github.com/ioam/holoviews/blob/master/LICENSE.txt>`_ Python
+library for exploratory machine learning research in Earth science.
+
+We recommend the `Getting Started Guide <getting_started>`_ to learn
+the basic concepts and start using Project as quickly as possible.
+
+The `User Guide <user_guide>`_ goes into key concepts more deeply when
+you are ready for further study.
+
+The `API <Reference_Manual>`_ is the definitive guide to each EarthML
+object.
+
+Please feel free to report `issues
+<https://github.com/pyviz-topics/EarthML/issues>`_ or `contribute code
+<https://github.com/pyviz-topics/EarthML/>`_.
+
+
+
+Installation
+------------
+
+To be completed.
+
+
+
+.. raw:: html
+
+   </div>
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   Introduction <self>
+   Getting Started <getting_started/index>
+   User Guide <user_guide/index>
+   Topics <topics/index>
+   API <Reference_Manual/index>
+   FAQ

doc/topics/index.rst

@@ -0,0 +1,26 @@
+******
+Topics
+******
+
+Examples of what can be done with EarthML.
+
+To learn how to use EarthML, see the
+`Getting Started <../getting_started/index.html>`_ guide.
+
+Detailed documentation is contained in the `User Guide
+<../user_guide/index.html>`_.
+
+Contents:
+
+* `landsat_spectral_clustering <landsat_spectral_clustering.html>`_
+   Unsupervised clustering of LANDSAT data
+
+* `Carbon_Flux <Carbon_Flux.html>`_
+   Visualizing and estimating global carbon flux from fluxnet and RSIF data.
+
+* `Walker_Lake <Walker_Lake.html>`_
+   Visualizing the change in the NDVI over time for a great saline lake. 
+
+* `landsat_classifier_ensemble <landsat_classifier_ensemble.html>`_
+   A comparison of scikit learn classifiers using LANDSAT 5 and LANDSAT 8 data sets.
+

doc/user_guide/index.rst

@@ -0,0 +1,31 @@
+**********
+User Guide
+**********
+
+Most of the functionality developed in the EarthML project is in the
+various general-purpose open-source Python packages like `Bokeh
+<http://bokeh.pydata.org>`_, `HoloViews <http://holoviews.org>`_, and
+`Datashader <http://datashader.org>`_:
+
+
+* `Introduction and Workflow <01_Introduction_and_Workflow.html>`_: Overview of the recommended workflow.
+
+* `Data Ingestion with Intake] <02_Data_Ingestion_with_Intake.html>`_: Loading large data sets efficiently with `intake <https://github.com/ContinuumIO/intake>`_.
+
+* `Alignment and Preprocessing <03_Alignment_and_Preprocessing.html>`_: How to prepare your data for the machine learning pipeline.
+
+* `Machine Learning <04_Machine_Learning.html>`_: Specifying a `scikit-learn <http://scikit-learn.org/stable/index.html>`_ pipeline to ingest the prepared training data.
+
+* `Data Visualization <05_Data_Visualization.html>`_: How to visualize your data throughout the workflow, starting from data ingestion to the final machine learning product.
+
+
+.. toctree::
+    :titlesonly:
+    :hidden:
+    :maxdepth: 2
+
+    Introduction and Workflow <01_Introduction_and_Workflow>
+    Data Ingestion with Intake <02_Data_Ingestion_with_Intake>
+    Alignment and Preprocessing <03_Alignment_and_Preprocessing>
+    Machine Learning <04_Machine_Learning>
+    Data Visualization <05_Data_Visualization>

examples/landsat_spectral_clustering.ipynb → examples/topics/landsat_spectral_clustering.ipynb

@@ -1529,6 +1529,7 @@
    "source": [
     "import rasterio\n",
     "import holoviews as hv\n",
+    "from holoviews.operation.datashader import regrid\n",
     "import dask.array as da\n",
     "from dask_ml.cluster import SpectralClustering\n",
     "from dask.distributed import Client\n",
@@ -1794,7 +1795,7 @@
    "outputs": [],
    "source": [
     "%%opts Image (cmap='viridis')\n",
-    "hv.Image(arr).relabel('Image') + hv.Image(c).relabel('Clustered')"
+    "regrid(hv.Image(arr)).relabel('Image') + regrid(hv.Image(c)).relabel('Clustered')"
    ]
   },
   {

examples/user_guide/01_Introduction_and_Workflow.ipynb

@@ -0,0 +1,24 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this user guide, the core concepts of EarthML are introduced with the aim of outlining a typical, explorative machine learning workflow. This workflow is composed of the following steps that are explained in more detail in the following user guides:\n",
+    "\n",
+    "1. [Data Ingestion with Intake](./02_Data_Ingestion_with_Intake.ipynb): Loading large data sets efficiently with [`intake`](https://github.com/ContinuumIO/intake).\n",
+    "2. [Alignment and Preprocessing](./03_Alignment_and_Preprocessing.ipynb): How to prepare your data for the machine learning pipeline.\n",
+    "3. [Machine Learning](./04_Machine_Learning.ipynb): Specifying a [`scikit-learn`](http://scikit-learn.org/stable/index.html) pipeline to ingest the prepared training data.\n",
+    "4. [Data Visualization](./05_Data_Visualization.ipynb): How to visualize your data throughout the workflow, starting from data ingestion to the final machine learning product."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

examples/user_guide/02_Data_Ingestion_with_Intake.ipynb

@@ -0,0 +1,21 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Machine learning tasks are typically data heavy, requiring either labelled data for supervised learning or unlabelled data for unsupervised learning. In this user guide, the [`intake`](https://github.com/ContinuumIO/intake) library is used to fetch large datasets from remote data sources efficiently, including built in caching to avoid unncessary download when the files are available locally.\n",
+    "\n",
+    "Once you have loaded your data, you will typically need to reshape it appropriately before it can be fed into a machine learning pipeline. These steps are detailed in the next user guide [Alignment_and_Preprocessing](03_Alignment_and_Preprocessing.ipynb)."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

examples/user_guide/03_Alignment_and_Preprocessing.ipynb

@@ -0,0 +1,19 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once the data is made available via `intake` as detailed in the  [Data_Ingestion_with_Intake](./02_Data_Ingestion_with_Intake.ipynb) user guide, the next step is to ensure the data has been appropriately reshaped and aligned across data sources for consumption by the machine learning pipeline, which you can learn about in the next user guide [Machine_Learning](./04_Machine_Learning.ipynb).\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}