add DropOut op and stub to Documentation ToC (#1675)

* add DropOut op and stub to Documentation ToC

* cleanup stub for dropout and add template for op additions

* add checklist as helper for op_stub

contrib/docker/Dockerfile.ngraph

@@ -24,16 +24,13 @@ RUN apt-get update && apt-get install -y \
         git \
         wget patch diffutils zlib1g-dev libtinfo-dev \
         doxygen graphviz \
-        python-pip
+        python-sphinx python3-sphinx \
+        python-pip  
 
 RUN apt-get clean autoclean && \
     apt-get autoremove -y
 RUN pip install --upgrade pip
 
-# need to use sphinx version 1.6 to build docs
-# installing with apt-get install python-sphinx installs sphinx version 1.3.6 only
-# added install for python-pip above and
-# installed sphinx with pip to get the updated version 1.6.5
 # allows for make html build under the doc/source directory as an interim build process
 RUN pip install sphinx
 RUN pip install breathe

contrib/docker/Dockerfile.ngraph.centos74

@@ -23,6 +23,7 @@
 FROM centos:7
 
 # Added install for perl Data::Dumper to avoid a compile error
+# Sphinx docs specify python-sphinx package
 RUN yum -y update && \
     yum -y --enablerepo=extras install epel-release && \
     yum -y install \
@@ -30,7 +31,7 @@ RUN yum -y update && \
     cmake3 make \
     git \
     wget patch diffutils zlib-devel ncurses-devel libtinfo-dev \
-    python python-devel python3-sphinx python-setuptools \
+    python python-devel python-sphinx python-setuptools \
     doxygen graphviz \
     which \
     'perl(Data::Dumper)'

contrib/docker/Dockerfile.ngraph.ubuntu1604

@@ -24,7 +24,7 @@ RUN apt-get update && apt-get install -y \
         git \
         wget patch diffutils zlib1g-dev libtinfo-dev \
         doxygen graphviz \
-        python-pip python3-pip
+        python-pip python3-sphinx
 
 RUN apt-get clean autoclean && \
     apt-get autoremove -y
@@ -35,7 +35,7 @@ RUN pip install --upgrade pip
 # added install for python-pip above and
 # installed sphinx with pip to get the updated version 1.6.5
 # allows for make html build under the doc/source directory as an interim build process
-RUN pip install sphinx==1.7.5
+RUN pip install sphinx
 RUN pip install breathe
 
 # need numpy to successfully build docs for python_api

doc/sphinx/source/ops/checklist.txt

+checklist.txt
+
+1. Add classes for the op to src/ngraph/op
+2. Add the op to src/ngraph/op/op_tbl.hpp
+3. Add a reference kernel to src/runtime/reference
+4. Add a call to the reference kernel to src/interpreter/int_backend.hpp
+5. Add the header for the op class to src/ngraph/ngraph.hpp
+6. Add serializer *and* deserializer support to src/ngraph/serializer.cpp
+7. Add type propagation tests to test/type_prop.cpp
+8. Add execution tests to test/backend_test.in.cpp
+9. Update unit test manifests for non-INTERPRETER backends (CPU, GPU, INTELGPU) to exclude your new execution tests
+  (Or, if you know what you're doing, update those backends to support your new op.)
+10. Add .rst files documenting the op to doc/sphinx/source/ops
+11. Add links to your new doc files to doc/sphinx/source/ops/index.rst
\ No newline at end of file

doc/sphinx/source/ops/drop_out.rst

+.. drop_out.rst:
+
+#######
+DropOut
+#######
+
+.. code-block:: cpp
+
+   DropOut  // DropOut 
+
+
+Description
+===========
+
+.. TODO
+
+Inputs
+------
+
+.. TODO
+
++-----------------+-------------------------+----------------------------------+
+|                 |                         |                                  |
++=================+=========================+==================================+
+|                 |                         |                                  |
++-----------------+-------------------------+----------------------------------+
+
+Attributes
+----------
+
+.. TODO
+
++-------------------------------+-----------------------------------------------+
+| Name                          | Description                                   |
++===============================+===============================================+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+
+Outputs
+-------
+
+.. TODO
+
++-----------------+-------------------------+--------------------------------+
+| Name            | Element Type            | Shape                          |
++=================+=========================+================================+
+| ``output``      |                         |                                |
++-----------------+-------------------------+--------------------------------+
+
+
+Mathematical Definition
+=======================
+
+.. TODO update this
+
+
+
+
+C++ Interface
+=============
+
+.. coming soon
\ No newline at end of file

doc/sphinx/source/ops/index.rst

@@ -67,6 +67,7 @@ Not currently a comprehensive list.
    * :doc:`cosh`
    * :doc:`divide`
    * :doc:`dot`
+   * :doc:`drop_out`
    * :doc:`equal`
    * :doc:`exp`
    * :doc:`floor`
@@ -122,6 +123,7 @@ Not currently a comprehensive list.
    cosh.rst
    divide.rst
    dot.rst
+   drop_out.rst
    equal.rst
    exp.rst
    floor.rst

doc/sphinx/source/ops/op_stub.rst

+:orphan:
+
+.. op_stub: 
+
+
+
+#######
+Op Stub
+#######
+
+.. code-block:: cpp
+
+   Op  // Put your op's short description here 
+
+
+Description
+===========
+
+.. TODO
+
+Put your op's longer description here. 
+
+
+
+Inputs
+------
+
+.. TODO
+
++-----------------+-------------------------+----------------------------------+
+| Name            |                         |                                  |
++=================+=========================+==================================+
+|                 |                         |                                  |
++-----------------+-------------------------+----------------------------------+
+
+Attributes
+----------
+
+.. TODO
+
++-------------------------------+-----------------------------------------------+
+| Name                          | Description                                   |
++===============================+===============================================+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+|                               |                                               |
++-------------------------------+-----------------------------------------------+
+
+Outputs
+-------
+
+.. TODO
+
++-----------------+-------------------------+--------------------------------+
+| Name            | Element Type            | Shape                          |
++=================+=========================+================================+
+| ``output``      |                         |                                |
++-----------------+-------------------------+--------------------------------+
+
+
+Mathematical Definition
+=======================
+
+.. TODO update this
+
+
+
+
+C++ Interface
+=============
+
+.. see other ops for how this is done; also see checklist.txt 
\ No newline at end of file

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

@@ -32,7 +32,7 @@ computation composed of basic building blocks which we call
 optimal semantically equivalent groups of kernels for the backend(s)
 in use. Thus, we expect that adding of new Core ops should be
 infrequent and that most functionality instead gets added with new
-functions that build sub-graphs from existing core ops.
+functions that build sub-graphs from existing core ops. 
 
 
 Coding style
@@ -259,4 +259,5 @@ it is automatically enforced and reduces merge conflicts.
        int* z;
 
 
-.. _`Apache 2`: https://www.apache.org/licenses/LICENSE-2.0
+.. _Apache 2: https://www.apache.org/licenses/LICENSE-2.0
+.. _repo wiki: 
\ No newline at end of file

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

@@ -15,38 +15,36 @@
 .. limitations under the License.
 .. ---------------------------------------------------------------------------
 
-Documentation Contributor README
-================================
+nGraph™ Library docs  
+====================
 
-How to start contributing?
---------------------------
+Read this for changes affecting anything in ``ngraph/doc``
+----------------------------------------------------------
 
-For Intel® nGraph™ library core project components only, please submit a PR with 
+For updates to the Intel® nGraph™ Library ``/doc`` repo, please submit a PR with 
 any changes or ideas you'd like integrated. This helps us maintain trackability 
 with respect to additions or feature requests.
 
 If you prefer to use a containerized application, like Jupyter\* notebooks, 
-Google Docs\*, or MS Word\* to write and share documentation contributions, 
+Google Docs\*, or MS Word\* to explain, write, or share documentation contributions, 
 you can convert the ``doc/sphinx/source/*.rst`` files to another format with a tool 
 like ``pypandoc`` and share a link to your docs on our `wiki`_.
 
 Another option is to fork the `ngraph repo`_, essentially snapshotting it at 
 that point in time, and to build a Jupyter\* notebook or other set of docs around 
-it for a specific use case; then share contribution with us directly on our wiki.  
+it for a specific use case; then share a link with the community on our wiki.   
 
 .. note:: Please do not submit Jupyter* notebook code to the Intel nGraph library 
    or core repos; best practice is to maintain any project-specific examples, 
-   tests, or walk-throughs separately. Alternatively, you may wish to upstream 
-   documentation contributions directly to whatever frontend framework supports 
-   your model or example. 
+   tests, or walk-throughs separately. 
 
 
 Documenting source code examples 
 --------------------------------
 
 When **verbosely** documenting functionality of specific sections of code -- whether 
-they are entire code blocks within a file, or code strings that are **outside** the 
-Intel nGraph `documentation repo`_, here is an example of best practice: 
+they are entire code blocks within a file, or code strings that are **outside** 
+the Intel nGraph `documentation repo`_, here is an example of best practice: 
 
 Say a file has some interesting functionality that could benefit from more 
 explanation about one or more of the pieces in context. To keep the "in context" 
@@ -67,10 +65,14 @@ And the raw code will render as follows
    :lines: 20-31
 
 You can now verbosely explain the code block without worrying about breaking
-the code.  The trick here is to add the file you want to reference relative to 
+the code. The trick here is to add the file you want to reference relative to 
 the folder where the ``Makefile`` is that generates the documentation you're 
-writing. See the **note** at the bottom of this page for more detail about how 
-this works in the alpha version of Intel nGraph library documentation. 
+writing. 
+
+
+See the **note** at the bottom of this page for more detail about how 
+this works in the current |version| version of Intel nGraph library 
+documentation. 
 
 
 Adding captions to code blocks 
@@ -85,16 +87,16 @@ line numbers, and add a caption:
 
   .. literalinclude:: ../../../examples/abc/abc.cpp
      :language: cpp
-     :lines: 20-31
-     :caption: "sample caption"
+     :lines: 48-56
+     :caption: "caption for a block of code that initializes tensors"
 
 
 and the generated output will show readers of your helpful documentation
 
 .. literalinclude:: ../../../examples/abc/abc.cpp
    :language: cpp
-   :lines: 20-31
-   :caption: "sample caption for a code block"
+   :lines: 48-56
+   :caption: "caption for a block of code that initializes tensors"
 
 Our documentation practices are designed around "write once, reuse" that we can 
 use to prevent code bloat.  See the :doc:`code-contributor-README` for our code