. helping people document code more efficiently (#1090)

doc/examples/README.md

+# nGraph Code Examples
+
+`You are at: ngraph/doc/examples/README.md`
+
+The code examples in this folder are for documentation purposes. 
+Any modifications to the code or comments on example programs 
+in this directory have DOCUMENTATION BREAKING IMPLICATIONS. You 
+are welcome to refactor these code examples, if you think they 
+can be made more clear; however, you must also find and update 
+all `.rst` documentation files affected by your change(s). Every 
+example file added to this directory must be accompanied separate 
+and proper documentation files formatted in `.rst`, as per the 
+specification in our [doc contributor README] file.
+
+
+
+
+[doc contributor README](http://ngraph.nervanasys.com/docs/latest/project/doc-contributor-README.html) 

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

@@ -77,7 +77,7 @@ We begin by building the graph, starting with the input parameter
 ``X``. We define a fully-connected layer, including a parameter for
 weights and bias.
 
-.. literalinclude:: ../../../examples/mnist_mlp.cpp
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
    :lines: 124-136
 
@@ -85,7 +85,7 @@ weights and bias.
 We repeat the process for the next layer, which we
 normalize with a ``softmax``.
 
-.. literalinclude:: ../../../examples/mnist_mlp.cpp
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
    :lines: 138-149
 
@@ -99,7 +99,7 @@ We use cross-entropy to compute the loss. nGraph does not currenty
 have a cross-entropy op, so we implement it directly, adding clipping
 to prevent underflow.
 
-.. literalinclude:: ../../../examples/mnist_mlp.cpp
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
    :lines: 151-166
 
@@ -116,7 +116,7 @@ interpreted frameworks. In nGraph, we augment the loss computation
 with computations for the weight adjustments. This allows the
 calculations for the adjustments to be further optimized.
 
-.. literalinclude:: ../../../examples/mnist_mlp.cpp
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
    :lines: 172-175
 
@@ -131,7 +131,7 @@ update computation for ``N`` will be given by the node
 The different update nodes will share intermediate computations. So to
 get the updated values for the weights we just say:
 
-.. literalinclude:: ../../../examples/mnist_mlp.cpp
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
    :lines: 177-217
 
@@ -151,7 +151,7 @@ use the same nodes in different functions, nGraph currently does not
 allow the same nodes to be compiled in different functions, so we
 compile clones of the nodes.
 
-.. literalinclude:: ../../../examples/mnist_mlp.cpp
+.. literalinclude:: ../../../examples/mnist_mlp/mnist_mlp.cpp
    :language: cpp
    :lines: 220-226
 

doc/sphinx/source/howto/execute.rst

@@ -71,7 +71,7 @@ They receive their values from outside of the graph, so they have no inputs.
 They have attributes for the element type and the shape of the tensor that will 
 be passed to them.
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 25-29
 
@@ -81,7 +81,7 @@ shape ``(2, 3)`` and a row-major element layout.
 To create a graph for ``(a + b) * c``, first make an ``op::Add`` node with inputs 
 from ``a`` and ``b``, and an ``op::Multiply`` node from the add node and ``c``:
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 31-32
 
@@ -94,7 +94,7 @@ type and shape of its unique output.
 
 Once the graph is built, we need to package it in a ``Function``:
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 35-36
 
@@ -131,7 +131,7 @@ for additional details.
 
 To continue with our original example and select the ``"CPU"`` backend: 
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 38-39
 
@@ -168,7 +168,7 @@ Backends are responsible for managing storage. If the storage is off-CPU, caches
 are used to minimize copying between device and CPU. We can allocate storage for 
 the three parameters and the return value as follows:
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 41-46
 
@@ -186,7 +186,7 @@ Initialize the inputs
 
 Next we need to copy some data into the tensors.
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 48-55
 
@@ -201,7 +201,7 @@ Invoke the computation
 To invoke the function, we simply pass argument and resultant tensors to the 
 call frame:
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 57-58
 
@@ -213,7 +213,7 @@ Access the outputs
 
 We can use the ``read`` method to access the result:
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 60-77
 
@@ -222,7 +222,7 @@ We can use the ``read`` method to access the result:
 Put it all together
 ===================
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :linenos:
    :caption: "The (a + b) * c example for executing a computation on nGraph"

doc/sphinx/source/howto/import.rst

@@ -149,7 +149,7 @@ specify the relative path to the location of the ``.onnx`` file.
 Enable ONNX and load an ONNX file from disk
 --------------------------------------------
 
-.. literalinclude:: ../../../examples/onnx_example.py
+.. literalinclude:: ../../../examples/onnx/onnx_example.py
    :language: python
    :lines: 17-19
 
@@ -157,7 +157,7 @@ Enable ONNX and load an ONNX file from disk
 Convert an ONNX model to an ngraph model 
 -------------------------------------------
 
-.. literalinclude:: ../../../examples/onnx_example.py
+.. literalinclude:: ../../../examples/onnx/onnx_example.py
    :language: python
    :lines: 22-23
 
@@ -184,7 +184,7 @@ input parameters for the computation which generates the output.
 Using ngraph_api, create a callable computation object
 -------------------------------------------------------
 
-.. literalinclude:: ../../../examples/onnx_example.py
+.. literalinclude:: ../../../examples/onnx/onnx_example.py
    :language: python
    :lines: 27-29
 
@@ -192,14 +192,14 @@ Using ngraph_api, create a callable computation object
 Load or create an image
 ------------------------
 
-.. literalinclude:: ../../../examples/onnx_example.py
+.. literalinclude:: ../../../examples/onnx/onnx_example.py
    :language: python
    :lines: 32-33
 
 Run ResNet inference on picture
 ---------------------------------
 
-.. literalinclude:: ../../../examples/onnx_example.py
+.. literalinclude:: ../../../examples/onnx/onnx_example.py
    :language: python
    :lines: 36-37
  
@@ -207,7 +207,7 @@ Run ResNet inference on picture
 Put it all together
 ===================
 
-.. literalinclude:: ../../../examples/onnx_example.py
+.. literalinclude:: ../../../examples/onnx/onnx_example.py
    :language: python
    :lines: 17-37
    :caption: "Demo sample code to run inference with nGraph"

doc/sphinx/source/howto/operator.rst

@@ -10,13 +10,13 @@ building of graphs.
 Several C++ operators are overloaded to simplify graph construction.
 For example, the following:
 
-.. literalinclude:: ../../../examples/abc.cpp
+.. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
    :lines: 32-32
 
 can be simplified to:	   
 
-.. literalinclude:: ../../../examples/abc_operator.cpp
+.. literalinclude:: ../../../examples/abc_operator/abc_operator.cpp
    :language: cpp
    :lines: 31
 

doc/sphinx/source/howto/update.rst

@@ -15,7 +15,7 @@ An example from C++
 Let's start with a simple C++ example, a function ``count`` that
 returns how many times it has already been called:
 
-.. literalinclude:: ../../../examples/update.cpp
+.. literalinclude:: ../../../examples/update/update.cpp
    :language: cpp
    :lines: 20-24
    :caption: update.cpp
@@ -27,13 +27,13 @@ convert this to use a stateless function, define a function that
 takes the current value of ``counter`` as an argument and returns the
 updated value.
 
-.. literalinclude:: ../../../examples/update.cpp
+.. literalinclude:: ../../../examples/update/update.cpp
    :language: cpp
    :lines: 26-29
 
 To use this version of counting,
 
-.. literalinclude:: ../../../examples/update.cpp
+.. literalinclude:: ../../../examples/update/update.cpp
    :language: cpp
    :lines: 36-48
 

doc/sphinx/source/project/doc-contributor-README.rst

@@ -55,14 +55,14 @@ source file:
 
 ::
 
-  .. literalinclude:: ../../../../src/ngraph/descriptor/primary_tensor_view.cpp
+  .. literalinclude:: ../../../examples/abc/abc.cpp
      :language: cpp
      :lines: 20-31
 
 And the raw code will render as follows
 
 
-.. literalinclude:: ../../../../src/ngraph/descriptor/primary_tensor_view.cpp 
+.. literalinclude:: ../../../examples/abc/abc.cpp 
    :language: cpp
    :lines: 20-31