Note experimental Codegen (#2672)

* [ONNX] Add documentation

* Update documentation contributor's instructions

* Doc theme to match ngraph.ai

* Minor formatting fixes and PR feedback

* ToC fixes

* ToC fixes

* Add changes

* Be consistent with BUILDDIR

* Be consistent with substitution

* Update Makefile

* Update style check, add feedback from reviewers, remove outdated link on ReleaseNotes

doc/sphinx/ngraph_theme/static/css/theme.css

@@ -2737,14 +2737,14 @@ span[id*='MathJax-Span'] {
   height: 35.2px;
   display: inline-block;
   line-height: 44.8px;
-  padding: 0.1 0.1 em;
-  margin-left: 0.31em;
+  padding: 0.1 0.1;
+  margin-left: 0.43em;
   margin-bottom: 0;
   display: block;
   font-family: "NeoSansIntel", sans;
   font-weight: bolder;
   text-transform: uppercase;
-  font-size: 107%;
+  font-size: 103%;
   color: #abb6cd;
   /* background-color: #53607d; */
   white-space: nowrap;

doc/sphinx/source/core/passes/list-of-passes.rst

@@ -50,12 +50,15 @@ Memory Assignment Passes
 Codegen Passes
 ==============
 
+.. important:: Codegen is currently experimental only. 
+
+
 .. csv-table::
    :header: "Codegen Passes", "More Detail"
    :widths: 29, 31
    :escape: ~
 
-   ``CommonFunctionCollection``, ""
+   ``CommonFunctionCollection``, "Experimental Only"
 
 
 Debug Passes

doc/sphinx/source/frameworks/index.rst

@@ -14,15 +14,16 @@ Current framework integrations
 
 
 A framework is "supported" when there is a framework :term:`bridge` that can be 
-cloned from one of our GitHub repos and built to connect to nGraph device backends, 
-all the while maintaining the framework's programmatic or user interface. Bridges 
+cloned from one of our GitHub repos and built to connect to nGraph device 
+backends while maintaining the framework's programmatic or user interface. Bridges 
 currently exist for the TensorFlow\* and MXNet\* frameworks. 
 
 .. figure:: ../graphics/whole-stack.png
     :width: 733px
     :alt: JiT compiling of a computation
 
-    :abbr:`Just-in-Time (JiT)` Compiling for computation
+    :abbr:`Just-in-Time (JiT)` Compiling for computation. nGraph `Core` components 
+    are colored in blue. 
 
 Once connected via the bridge, the framework can then run and train a deep 
 learning model with various workloads on various backends using nGraph Compiler 
@@ -33,13 +34,13 @@ end use by data scientists, or for deployment in cloud container environments,
 nGraph Core ops and the nGraph C++ Library are designed for framework builders 
 themselves. We invite anyone working on new and novel frameworks or neural 
 network designs to explore our highly-modularized stack of components that can 
-be implemented or integrated in virtually limitless ways.
+be implemented or integrated in countless ways.
 
-Please read the articles in this section if you are considering incorporating 
-components from the nGraph Compiler stack in your framework or neural network 
-design. Articles here are also useful if you are working on something 
-built-from-scratch, or on an existing framework that is less widely-supported 
-than the popular frameworks like TensorFlow and PyTorch. 
+Please read this section if you are considering incorporating components from 
+the nGraph Compiler stack in your framework or neural network design. Contents 
+here are also useful if you are working on something built-from-scratch, or on 
+an existing framework that is less widely-supported than the popular frameworks 
+like TensorFlow and PyTorch. 
 
 .. figure:: ../graphics/translation-flow-to-ng-fofx.png
    :width: 725px

doc/sphinx/source/index.rst

@@ -24,18 +24,18 @@ nGraph Compiler stack
 
 `nGraph`_ is an open-source graph compiler for :abbr:`Artificial Neural Networks (ANNs)`. 
 The nGraph Compiler stack provides an inherently efficient graph-based compilation 
-infrastructure designed to be compatible with the many of the upcoming 
+infrastructure designed to be compatible with many upcoming 
 :abbr:`Application-Specific Integrated Circuits (ASICs)`, like the Intel® Nervana™ 
 Neural Network Processor (Intel® Nervana™ NNP), while also unlocking a massive 
-performance boost on any existing hardware targets in your neural network: both GPUs 
-and CPUs. Using its flexible infrastructure, you will find it becomes much easier 
-to create Deep Learning (DL) models that can adhere to the "write once, run anywhere" 
-mantra that enables your AI solutions to easily go from concept to production to scale.
+performance boost on any existing hardware targets for your neural network: both 
+GPUs and CPUs. Using its flexible infrastructure, you will find it becomes much 
+easier to create Deep Learning (DL) models that can adhere to the "write once, 
+run anywhere" mantra that enables your AI solutions to easily go from concept to 
+production to scale.
 
 Frameworks using nGraph to execute workloads have shown `up to 45X`_ performance 
 boost compared to native implementations. For a high-level overview, see the 
-:doc:`project/introduction`.
-
+:doc:`project/introduction` and our latest :doc:`project/release-notes`.
 
 .. toctree::
    :maxdepth: 1

doc/sphinx/source/project/contrib.md

@@ -128,14 +128,13 @@ Although not always ideal, it is automatically enforced and reduces
 merge conflicts.
 
 -   The .clang-format file located in the root of the project specifies
-    our format.
-    -   The script maint/apply-code-format.sh enforces that formatting
-        at the C/C++ syntactic level.
-    -   The script at maint/check-code-format.sh verifies that the
-        formatting rules are met by all C/C++ code (again, at the
-        syntax level). The script has an exit code of `0` when code
-        meets the standard and non-zero otherwise. This script does
-        *not* modify the source code.
+    our format. Simply run:
+
+    ``` make style-check && 
+        make style-apply```
+    
+
+
 -   Formatting with `#include` files:
     -   Put headers in groups separated by a blank line. Logically order
         the groups downward from system-level to 3rd-party to `ngraph`.

doc/sphinx/source/project/contribution-guide.rst

@@ -156,14 +156,12 @@ use **clang format** to enforce certain formatting. Although not always ideal,
 it is automatically enforced and reduces merge conflicts.
 
 - The :file:`.clang-format` file located in the root of the project specifies
-  our format.
-
-  * The script :file:`maint/apply-code-format.sh` enforces that formatting
-    at the C/C++ syntactic level.
-  * The script at :file:`maint/check-code-format.sh` verifies that the formatting
-    rules are met by all C/C++ code (again, at the syntax level). The script has
-    an exit  code of ``0`` when code meets the standard and non-zero otherwise.
-    This script does *not* modify the source code.
+  our format.  Simply run:  
+
+  .. code-block:: console
+
+     $ make style-check
+     $ make style-apply
 
 - Formatting with ``#include`` files:
 

doc/sphinx/source/project/introduction.rst

@@ -95,11 +95,11 @@ optimal:
    :width: 555px
    :alt: 
 
-The following computation is constructed to execute ``(A+B)*C``, but in the 
-context of nGraph, we can further optimize the graph to be represented as ``A*C``. 
-From the first graph shown on the left, the operation on the constant ``B`` can 
-be computed at the compile time (known as constant folding), and the graph can 
-be further simplified to the one on the right because the constant has value of 
+The computation is constructed to execute ``(A+B)*C``, but in the context of 
+nGraph, we can further optimize the graph to be represented as ``A*C``. From the 
+first graph shown on the left, the operation on the constant ``B`` can be 
+computed at the compile time (known as constant folding), and the graph can be 
+further simplified to the one on the right because the constant has value of 
 zero. Without such graph-level optimizations, a deep learning framework with a 
 kernel library will compute all operations, and the resulting execution will be 
 suboptimal. 
@@ -153,9 +153,9 @@ PlaidML addresses the kernel explosion problem in a manner that lifts a heavy
 burden off kernel developers. It automatically lowers networks from nGraph 
 into Tile, a :abbr:Domain-Specific Language (DSL) designed for deep learning 
 that allows developers to express how an operation should calculate tensors in
-an intuitive, mathematical form. Integration of PlaidML with nGraph means 
-extra flexibility to support newer deep learning models in the absence of 
-by-hand optimized kernels for the new operations.
+an intuitive, mathematical form via `Stripe`_. Integration of PlaidML with 
+nGraph means extra flexibility to support newer deep learning models in the 
+absence of by-hand optimized kernels for the new operations.
 
 
 Solution: nGraph and PlaidML
@@ -164,17 +164,17 @@ Solution: nGraph and PlaidML
 Each of the problems above can be solved with nGraph and PlaidML. We developed 
 nGraph and integrated it with PlaidML so developers wanting to craft solutions 
 with :abbr:`AI (Artificial Intelligence)` won't have to face such a steep 
-learning curve in taking their concepts from design to production to scale. The 
-fundamental efficiencies behind Moore's Law are not dead; rather than fitting 
-`more transistors on denser and denser circuits`_, we're enabling advances 
-in compute with more transformers on denser and more data-heavy 
-:abbr:`Deep Learning Networks (DNNs)`, and making it easier to apply  
+learning curve in taking their concepts from design to production, and to scale. 
+The fundamental efficiencies behind Moore's Law are not dead; rather than fitting 
+`more transistors on denser and denser circuits`_, with nGraph and PlaidML, 
+we're enabling advances in compute with more transformers on denser and more 
+data-heavy :abbr:`Deep Learning Networks (DNNs)`, and making it easier to apply  
 :abbr:`Machine Learning (ML)` to different industries and problems. 
 
 For developers with a neural network already in place, executing workloads using 
 the nGraph Compiler provides further performance benefits and allows for quicker 
-adaptation of models. It also make it much easier to upgrade hardware 
-infrastructure pieces as workloads grow and require more careful balancing.
+adaptation of models. It also makes it much easier to upgrade hardware 
+infrastructure pieces as workloads grow. 
 
 This documentation provides technical details of nGraph's core functionality, 
 framework and backend integrations. Creating a compiler stack like nGraph and 
@@ -188,4 +188,5 @@ will make life easier for many kinds of developers:
    a deep learning framework to their silicon.  
 
 
-.. _more transistors on denser and denser circuits: https://www.intel.com/content/www/us/en/silicon-innovations/moores-law-technology.html
\ No newline at end of file
+.. _more transistors on denser and denser circuits: https://www.intel.com/content/www/us/en/silicon-innovations/moores-law-technology.html
+.. _Stripe: https://arxiv.org/abs/1903.06498
\ No newline at end of file

doc/sphinx/source/project/release-notes.rst

@@ -3,9 +3,17 @@
 Release Notes
 #############
 
-|release|
+This is |release|.
 
 
+
+
+
+CHANGELOG
+=========
+
+(Last updated September 2018)
+
 This release focuses on accelerating deep learning inference workloads on 
 Intel® Xeon® (CPU processor) and has the following key features: 
 
@@ -31,9 +39,3 @@ In our tests, the optimized workloads can perform up to 45X faster than native
 frameworks, and we expect performance gains for other workloads due to our 
 powerful :doc:`../core/fusion/index` feature.
 
-
-See also our recent `API changes`_
-
-
-
-.. _API changes: https://github.com/NervanaSystems/ngraph/blob/master/changes.md