Cleaner API doc reference for compile call (#2452)

* Cleaner API doc reference for compile call

* Add a useful table for nGraph namespaces

* Remove layout namespace

* Show exploding kernel problem on illustration like IEEE preso

doc/sphinx/ngraph.doxyfile

@@ -786,8 +786,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */tools/*
-                         */resource/*  
+EXCLUDE_PATTERNS       = */resource/*  
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

doc/sphinx/source/core/overview.rst

@@ -4,3 +4,30 @@
 Overview
 ========
 
+What follows here is a table of all documented namespaces with brief descriptions:
+
+
+Namespace List
+--------------
+ 
+.. csv-table::
+   :header: "Namespace", "Description", "Location in Repo", "Docs"
+   :widths: 23, 53, 13, 23
+   :escape: ~
+
+   ``ngraph``, The Intel nGraph C++ API, `Nngraph`_, Implicit namespace omitted from most API documentation
+   ``builder``, "Convenience functions that create additional graph nodes to implement commonly-used recipes; for example, auto-broadcast", `Nbuilder`_, Coming Soon
+   ``descriptor``, Descriptors are compile-time representations of objects that will appear at run-time, `Ndescriptor`_, Coming Soon
+   ``op``, Ops used in graph construction, `Nop`_, :doc:`../ops/index`
+   ``runtime``, The objects and methods used for executing the graph, `Nruntime`_, :doc:`../backend-support/cpp-api`
+
+
+.. _Nngraph: https://github.com/NervanaSystems/ngraph/tree/master/src/ngraph
+.. _Nbuilder: https://github.com/NervanaSystems/ngraph/tree/master/src/ngraph/builder
+.. _Ndescriptor: https://github.com/NervanaSystems/ngraph/tree/master/src/ngraph/descriptor
+.. _Nop: https://github.com/NervanaSystems/ngraph/tree/master/src/ngraph/op
+.. _Nruntime: https://github.com/NervanaSystems/ngraph/tree/master/src/ngraph/runtime
+
+
+
+

doc/sphinx/source/frameworks/validated/testing-latency.rst

@@ -16,7 +16,7 @@ MXNet\*, where `Intel has contributed efforts showing`_ how to work with our
 nGraph Compiler stack as an `experimental backend`_. Our approach provides 
 **more opportunities** to start working with different kinds of graph 
 optimizations **than would be available to the MXNet framework alone**, for 
-reasons outlined in our `features`_ documentation.
+reasons outlined in our `introduction`_ documentation.
 
 .. TODO : Link to latest on mxnet when/if they do this instead of linking to PR;
    keep in mind this tutorial will still work  regardless of the merge status of 
@@ -108,7 +108,7 @@ with the compiled model. At this point, we can test the model's performance.
 
 .. _experimental backend: https://github.com/apache/incubator-mxnet/pull/12502
 .. _Intel has contributed efforts showing: https://cwiki.apache.org/confluence/display/MXNET/MXNet+nGraph+integration+using+subgraph+backend+interface
-.. _features: http://ngraph.nervanasys.com/docs/latest/project/about.html#features
+.. _introduction: http://ngraph.nervanasys.com/docs/latest/project/introduction.html
 .. _gluon model zoo: https://github.com/apache/incubator-mxnet/blob/master/python/mxnet/gluon/model_zoo/vision/resnet.py#L499
 .. _subgraph acceleration API: https://cwiki.apache.org/confluence/display/MXNET/Unified+integration+with+external+backend+libraries
 .. _nGraph-MXNet: https://github.com/NervanaSystems/ngraph-mxnet/blob/master/README.md

doc/sphinx/source/howto/derive-for-training.rst

@@ -82,20 +82,20 @@ weights and bias:
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 127-139
+   :lines: 127-135
 
 
 Repeat the process for the next layer,
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 141-149
+   :lines: 138-146
 
 and normalize everything with a ``softmax``.
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 151-153
+   :lines: 148-150
 
 
 .. _loss:
@@ -109,7 +109,7 @@ underflow.
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 154-169
+   :lines: 154-166
 
 
 .. _backprop:
@@ -125,7 +125,7 @@ allows the calculations for the adjustments to be further optimized.
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 171-175
+   :lines: 169-172
 
 
 For any node ``N``, if the update for ``loss`` is ``delta``, the
@@ -135,13 +135,19 @@ update computation for ``N`` will be given by the node
 
    auto update = loss->backprop_node(N, delta);
 
+
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
+   :language: cpp
+   :lines: 177-181
+
+
 The different update nodes will share intermediate computations. So to
 get the updated values for the weights as computed with the specified 
-:doc:`backend <../backend-support/index>`.
+:doc:`backend <../backend-support/index>`:
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 177-217
+   :lines: 182-215
 
 
 .. _update:
@@ -161,5 +167,5 @@ compile clones of the nodes.
 
 .. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
-   :lines: 221-226
+   :lines: 216-224
 

doc/sphinx/source/index.rst

@@ -43,12 +43,13 @@ nGraph Compiler stack
 
    core/overview.rst
    Pattern matcher <fusion/index.rst>
-   nGraph ops <ops/about.rst>
+   nGraph Core Ops <ops/index.rst>
+   More about Ops <ops/about.rst>
    Graph construction <howto/index.rst>
    Using the Python API <python_api/index.rst>
    Compiler passes  <fusion/graph-rewrite.rst>
    buildlb.rst
-   Using the C++ API <ops/index.rst>
+   
    
 .. toctree::
    :maxdepth: 1