Merge pull request #19 from zillow/feature/docs-and-content

Feature/docs and content
zillow · Aug 18, 2020 · a4a80fd · a4a80fd
2 parents 0700f55 + adae72e
commit a4a80fd
Show file tree

Hide file tree

Showing 49 changed files with 1,260 additions and 51 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -6,44 +6,105 @@ Contributions are welcome, greatly appreciated and overall helps to improve the
 Report Bugs
 -----------
 
-Report bugs through `GitHub <https://github.com/zillow/luminaire/issues>`__.
-Make sure to tag label as ``bug``.
+Before creating a new issue, do check if a `bug was already reported <https://github.com/zillow/luminaire/labels/bug>`__
 
-Please provide detailed information about the bug and preferably part of the code that exhibits the problem.
+Report bugs through `GitHub Issues <https://github.com/zillow/luminaire/issues>`__:
+
+- Create a ``New Issue``
+- Provide detailed information about the bug and preferably part of the code that exhibits the problem
+- Make sure to tag label as ``bug``
 
 
 Fix Bugs
 --------
 
 Look through our `GitHub issues labeled "kind:bug"
 <https://github.com/zillow/luminaire/labels/bug>`__ for bugs.
-Issues which are unassigned can be owned to implement it.
 
-Create branch name with prefix ``bugfix/<bug-type>`` and once ready for review create a PR for ``master`` branch.
+Issues which are unassigned can be owned to implement it:
+
+- Create branch name with prefix ``bugfix/<bug-type>``
+- Add relevant code fix and test case
+- Update the package version inside ``setup.py``
+- Update the sphinx documentation
+- Once ready for review create a PR for ``master`` branch
+
 
 Report Features
 ---------------
 
-Report new features through `GitHub <https://github.com/zillow/luminaire/issues>`__.
-Make sure to tag label as ``feature``.
+Before creating a new feature request, do check if a `features was already requested <https://github.com/zillow/luminaire/labels/feature>`__
 
-Please provide detailed information about the feature, how it would work, benefits and scope.
+Report new features through `GitHub Issues <https://github.com/zillow/luminaire/issues>`__:
+
+- Create a ``New Issue``
+- Provide detailed information about the feature, how it would work, benefits and scope
+- Make sure to tag label as ``feature``
 
 
 Implement Features
 ------------------
 
 Look through the `GitHub issues labeled "kind:feature"
 <https://github.com/zillow/luminaire/labels/feature>`__ for features.
-Issues which are unassigned can be owned to implement it.
 
-Create branch name with prefix ``feature/<feature-type>`` and once ready for review create a PR for ``master`` branch.
+Issues which are unassigned can be owned to implement it:
+
+- Create branch name with prefix ``feature/<feature-type>``
+- Add relevant code and test case
+- Update the package version inside ``setup.py``
+- Update the sphinx documentation
+- Once ready for review create a PR for ``master`` branch.
+
+
+Updating Sphinx Documentation
+------------------------------
+
+We use `Sphinx <https://www.sphinx-doc.org/en/master/>`__ for code documentation and
+are hosted on our `Github pages <https://zillow.github.io/luminaire>`__
+
+All the code can be found under ``luminaire/docs_source``
+
+Steps to update Sphinx documentation:
 
-Do not forget to add test cases for any block of code you add.
+- On your local terminal cd till ``~/luminaire/docs_source`` folder
+- run ``make clean``, this will remove the folder ``~/luminaire/docs_source/_build``
+- run ``make html``, this will create files under ``~/luminaire/docs_source/_build``
+- ``git add ~/_build``
+- commit updated files as part of the PR
+
+
+Github Workflow (CI/CD)
+------------------------
+
+Github Workflow is used for CI/CD.
+
+Luminaire CI:
+
+One each commit `Luminaire CI Workflow <https://github.com/zillow/luminaire/actions?query=workflow%3A%22Luminaire+CI%22>`__ is invoked.
+Details about the Luminaire CI Workflow can be found `here <https://github.com/zillow/luminaire/blob/master/.github/workflows/python-app.yml>`__
+
+
+Luminaire CD:
+
+For releasing the code and making it available on PyPI, follow this steps:
+
+- ``setup.py`` has a new version specified
+- PR for ``master`` branch is approved and merged
+- `Create a new release <https://github.com/zillow/luminaire/releases/new>`__
+- Specify the ``Tag version`` with prefix ``v<version>`` example: v0.1.0
+- Select ``master`` branch
+- Provide relevant release title and description
+- If this is a pre-release check the box
+- Click ``Publish release`` and this will trigger `Luminaire CD Workflow <https://github.com/zillow/luminaire/blob/master/.github/workflows/python-publish.yml>`__
+- Check `PyPI release history <https://pypi.org/project/luminaire/#history>`__
 
 
 Submit Feedback
 ---------------
 
-The best way to send feedback is to `open an issue on GitHub <https://github.com/zillow/luminaire/issues>`__.
-Make sure to tag label as ``feedback``.
+The best way to send feedback is by `creating an issue on GitHub <https://github.com/zillow/luminaire/issues>`__.
+
+- Create a ``New Issue``
+- Provide detailed information about feedback
+- Make sure to tag label as ``feedback``
diff --git a/index.html b/index.html
@@ -1 +1,3 @@
-<meta http-equiv="refresh" content="0; url=./_build/html/index.html" />
+<!-- This file is used as the entry point for Github Pages which points to Sphinx documentation -->
+
+<meta http-equiv="refresh" content="0; url=./luminaire/docs_source/_build/html/index.html" />
diff --git a/luminaire/docs_source/Introduction.rst b/luminaire/docs_source/Introduction.rst
@@ -1,5 +1,5 @@
 Introduction
-========
+============
 
 .. image:: front.png
    :scale: 60%
@@ -11,6 +11,7 @@ Luminaire is a python package that provides ML driven solutions for monitoring t
 - **Fully Automatic:** Luminaire performs optimizations over different sets of hyperparameters and several model classes to pick the optimal model for the time series under consideration. No model configuration is required from the user.
 
 - **Supports Diverse Anomaly Detection Types:** Luminaire supports different detection types:
+
  - Outlier Detection
  - Data Shift Detection
  - Trend Change Detection

diff --git a/luminaire/docs_source/_build/doctrees/Introduction.doctree b/luminaire/docs_source/_build/doctrees/Introduction.doctree
diff --git a/luminaire/docs_source/_build/doctrees/basic_usage_tutorial/dataprofiling.doctree b/luminaire/docs_source/_build/doctrees/basic_usage_tutorial/dataprofiling.doctree
diff --git a/luminaire/docs_source/_build/doctrees/basic_usage_tutorial/outlier_batch.doctree b/luminaire/docs_source/_build/doctrees/basic_usage_tutorial/outlier_batch.doctree
diff --git a/luminaire/docs_source/_build/doctrees/basic_usage_tutorial/streaming.doctree b/luminaire/docs_source/_build/doctrees/basic_usage_tutorial/streaming.doctree
diff --git a/luminaire/docs_source/_build/doctrees/environment.pickle b/luminaire/docs_source/_build/doctrees/environment.pickle
diff --git a/luminaire/docs_source/_build/doctrees/user_guide/batch_models.doctree b/luminaire/docs_source/_build/doctrees/user_guide/batch_models.doctree
diff --git a/luminaire/docs_source/_build/doctrees/user_guide/exploration.doctree b/luminaire/docs_source/_build/doctrees/user_guide/exploration.doctree
diff --git a/luminaire/docs_source/_build/doctrees/user_guide/optimization.doctree b/luminaire/docs_source/_build/doctrees/user_guide/optimization.doctree
diff --git a/luminaire/docs_source/_build/doctrees/user_guide/streaming.doctree b/luminaire/docs_source/_build/doctrees/user_guide/streaming.doctree
diff --git a/luminaire/docs_source/_build/html/.buildinfo b/luminaire/docs_source/_build/html/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: d50b992c2fbe901c91156dcbef3201f3
+config: 733960dc2abca3fe27be8d50d43d50a2
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/luminaire/docs_source/_build/html/Introduction.html b/luminaire/docs_source/_build/html/Introduction.html
@@ -11,6 +11,8 @@
 
     <link rel="stylesheet" href="_static/css/redactor.css" type="text/css" />
 
+    <link rel="stylesheet" href="_static/graphviz.css" type="text/css" />
+
 
     <link rel="index" title="Index" href="genindex.html"/>
     <link rel="search" title="Search" href="search.html"/>

diff --git a/luminaire/docs_source/_build/html/_sources/Introduction.rst.txt b/luminaire/docs_source/_build/html/_sources/Introduction.rst.txt
@@ -1,5 +1,5 @@
 Introduction
-========
+============
 
 .. image:: front.png
    :scale: 60%
@@ -11,6 +11,7 @@ Luminaire is a python package that provides ML driven solutions for monitoring t
 - **Fully Automatic:** Luminaire performs optimizations over different sets of hyperparameters and several model classes to pick the optimal model for the time series under consideration. No model configuration is required from the user.
 
 - **Supports Diverse Anomaly Detection Types:** Luminaire supports different detection types:
+
  - Outlier Detection
  - Data Shift Detection
  - Trend Change Detection

diff --git a/...ire/docs_source/_build/html/_sources/basic_usage_tutorial/dataprofiling.rst.txt b/...ire/docs_source/_build/html/_sources/basic_usage_tutorial/dataprofiling.rst.txt
@@ -1,5 +1,5 @@
 Data Profiling
-========
+==============
 
 Luminaire *DataExploration* implements different exploratory data analysis to detect important information from time series data. This method can be used to impute missing data, detect the set of historical trend changes and change points (steady data shifts) which information can later be leveraged downstream in Luminaire outlier detection models.
 

diff --git a/...ire/docs_source/_build/html/_sources/basic_usage_tutorial/outlier_batch.rst.txt b/...ire/docs_source/_build/html/_sources/basic_usage_tutorial/outlier_batch.rst.txt
@@ -1,5 +1,5 @@
 Outlier Detection
-========
+=================
 
 Luminaire can detect outliers in time series data by modeling the predictive and the variational patterns of a time series trajectory. Luminaire is capable of tracking outliers for any time series data by applying two specific modeling capabilities:
 

diff --git a/luminaire/docs_source/_build/html/_sources/basic_usage_tutorial/streaming.rst.txt b/luminaire/docs_source/_build/html/_sources/basic_usage_tutorial/streaming.rst.txt
@@ -1,5 +1,5 @@
 Anomaly Detection for Streaming data
-========
+====================================
 
 Luminaire *WindowDensityModel* implements the idea of monitoring data over comparable windows instead of tracking individual data points as outliers. This is a useful approach for tracking anomalies over high frequency data, which tends to show a higher level of noise. Hence, tracking anomalies over streaming data essesntially means tracking sustained fluctuations.
 

diff --git a/luminaire/docs_source/_build/html/_sources/user_guide/batch_models.rst.txt b/luminaire/docs_source/_build/html/_sources/user_guide/batch_models.rst.txt
@@ -1,5 +1,5 @@
 Luminaire Outlier Detection Models: Structural Modeling
-===================
+=======================================================
 
 .. inheritance-diagram:: luminaire.model.lad_structural
     :parts: 1
@@ -8,7 +8,7 @@ Luminaire Outlier Detection Models: Structural Modeling
    :members:
 
 Luminaire Outlier Detection Models: Factoring holidays as exogenous
-===================
+===================================================================
 
 .. inheritance-diagram:: luminaire.model.model_utils
     :parts: 1
@@ -17,7 +17,7 @@ Luminaire Outlier Detection Models: Factoring holidays as exogenous
    :members:
 
 Luminaire Outlier Detection Models: Kalman Filter
-===================
+=================================================
 
 .. inheritance-diagram:: luminaire.model.lad_filtering
     :parts: 1

diff --git a/luminaire/docs_source/_build/html/_sources/user_guide/exploration.rst.txt b/luminaire/docs_source/_build/html/_sources/user_guide/exploration.rst.txt
@@ -1,5 +1,5 @@
 Data Exploration and Profiling
-===================
+==============================
 
 .. inheritance-diagram:: luminaire.exploration.data_exploration
     :parts: 1

diff --git a/luminaire/docs_source/_build/html/_sources/user_guide/optimization.rst.txt b/luminaire/docs_source/_build/html/_sources/user_guide/optimization.rst.txt
@@ -1,5 +1,5 @@
 Luminaire Configuration Optimization
-===================
+====================================
 
 .. inheritance-diagram:: luminaire.optimization.hyperparameter_optimization
     :parts: 1

diff --git a/luminaire/docs_source/_build/html/_sources/user_guide/streaming.rst.txt b/luminaire/docs_source/_build/html/_sources/user_guide/streaming.rst.txt
@@ -1,5 +1,5 @@
 Luminaire Streaming Anomaly Detection Models: Window Density Model
-===================
+==================================================================
 
 .. inheritance-diagram:: luminaire.model.window_density
     :parts: 1

diff --git a/luminaire/docs_source/_build/html/_static/graphviz.css b/luminaire/docs_source/_build/html/_static/graphviz.css
@@ -0,0 +1,19 @@
+/*
+ * graphviz.css
+ * ~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- graphviz extension.
+ *
+ * :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+img.graphviz {
+    border: 0;
+    max-width: 100%;
+}
+
+object.graphviz {
+    max-width: 100%;
+}
diff --git a/luminaire/docs_source/_build/html/basic_usage_tutorial/dataprofiling.html b/luminaire/docs_source/_build/html/basic_usage_tutorial/dataprofiling.html
@@ -11,6 +11,8 @@
 
     <link rel="stylesheet" href="../_static/css/redactor.css" type="text/css" />
 
+    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
+
 
     <link rel="index" title="Index" href="../genindex.html"/>
     <link rel="search" title="Search" href="../search.html"/>

diff --git a/luminaire/docs_source/_build/html/basic_usage_tutorial/optimization.html b/luminaire/docs_source/_build/html/basic_usage_tutorial/optimization.html
@@ -11,6 +11,8 @@
 
     <link rel="stylesheet" href="../_static/css/redactor.css" type="text/css" />
 
+    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
+
 
     <link rel="index" title="Index" href="../genindex.html"/>
     <link rel="search" title="Search" href="../search.html"/>

diff --git a/luminaire/docs_source/_build/html/basic_usage_tutorial/outlier_batch.html b/luminaire/docs_source/_build/html/basic_usage_tutorial/outlier_batch.html
@@ -11,6 +11,8 @@
 
     <link rel="stylesheet" href="../_static/css/redactor.css" type="text/css" />
 
+    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
+
 
     <link rel="index" title="Index" href="../genindex.html"/>
     <link rel="search" title="Search" href="../search.html"/>

diff --git a/luminaire/docs_source/_build/html/basic_usage_tutorial/streaming.html b/luminaire/docs_source/_build/html/basic_usage_tutorial/streaming.html
@@ -11,6 +11,8 @@
 
     <link rel="stylesheet" href="../_static/css/redactor.css" type="text/css" />
 
+    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
+
 
     <link rel="index" title="Index" href="../genindex.html"/>
     <link rel="search" title="Search" href="../search.html"/>

diff --git a/luminaire/docs_source/_build/html/basic_usage_tutorial/tutorials.html b/luminaire/docs_source/_build/html/basic_usage_tutorial/tutorials.html
@@ -11,6 +11,8 @@
 
     <link rel="stylesheet" href="../_static/css/redactor.css" type="text/css" />
 
+    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
+
 
     <link rel="index" title="Index" href="../genindex.html"/>
     <link rel="search" title="Search" href="../search.html"/>