[Py] Python nGraph API doc (#885)

* First version of nGraph Python API documentation pages.

* Remove use of (`) apostrophes since they generate Sphinx warnings.

* Fix submodule rendering in Sphinx PythonAPI docs

* Add updated index and conf py files

* Updated version of Python API doc.

* Better description for the autosummary

doc/sphinx/source/conf.py

@@ -16,11 +16,12 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import sys
+
+# Add path to nGraph Python API.
+sys.path.insert(0, os.path.abspath('../../../python'))
 
 # -- General configuration ------------------------------------------------
 
@@ -31,10 +32,15 @@ needs_sphinx = '1.6.5'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.mathjax',
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'breathe'
+    'breathe',
     ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -208,4 +214,10 @@ rst_epilog = u"""
    
 """
 
+# -- autodoc Extension configuration --------------------------------------
+
+autodoc_mock_imports = ['ngraph.impl', 'ngraph.utils']
+
+# -- autosummary Extension configuration ----------------------------------
 
+autosummary_generate = ['python_api/structure.rst']

doc/sphinx/source/index.rst

@@ -145,6 +145,7 @@ Contents
    project/index.rst
    framework-integration-guides.rst
    optimize/index.rst
+   python_api/index.rst
 
 
 Indices and tables

doc/sphinx/source/python_api/_autosummary/ngraph.exceptions.rst

+=================
+ngraph.exceptions
+=================
+
+.. automodule:: ngraph.exceptions
+
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   
+      NgraphError
+      NgraphTypeError
+      UserInputError
+   
+   
\ No newline at end of file

doc/sphinx/source/python_api/_autosummary/ngraph.ops.rst

+==========
+ngraph.ops
+==========
+
+.. automodule:: ngraph.ops
+
+   .. rubric:: Functions
+
+   .. autosummary::
+      :nosignatures:
+
+      absolute
+      acos
+      add
+      asin
+      atan
+      avg_pool
+      batch_norm
+      broadcast
+      ceiling
+      concat
+      constant
+      convert
+      convolution
+      cos
+      cosh
+      divide
+      dot
+      equal
+      exp
+      floor
+      function_call
+      get_output_element
+      greater
+      greater_eq
+      less
+      less_eq
+      log
+      logical_not
+      max
+      max_pool
+      maximum
+      min
+      minimum
+      multiply
+      negative
+      not_equal
+      one_hot
+      pad
+      parameter
+      power
+      prod
+      reduce
+      relu
+      replace_slice
+      reshape
+      reverse
+      select
+      sign
+      sin
+      sinh
+      slice
+      softmax
+      sqrt
+      subtract
+      sum
+      tan
+      tanh

doc/sphinx/source/python_api/_autosummary/ngraph.rst

+.. ngraph.rst
+
+######
+ngraph
+######
+
+
+.. automodule:: ngraph
+   :members:
+
+Submodules
+==========
+
+
+Exceptions
+----------
+
+.. automodule:: ngraph.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Ops
+---
+
+.. automodule:: ngraph.ops
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Runtime
+--------
+
+.. automodule:: ngraph.runtime
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

doc/sphinx/source/python_api/_autosummary/ngraph.runtime.rst

+==============
+ngraph.runtime
+==============
+
+.. automodule:: ngraph.runtime
+
+.. rubric:: Functions
+
+.. autosummary::
+   :nosignatures:
+
+   runtime
+
+.. rubric:: Classes
+
+.. autosummary::
+   :nosignatures:
+
+   Computation
+   Runtime
\ No newline at end of file

doc/sphinx/source/python_api/index.rst

+.. python_api/index.rst
+
+##########
+Python API
+##########
+
+This section contains nGraph™ Python API documentation. Python API exposes
+nGraph™ C++ operations to Python users. For quick-start you can find an example
+of the API usage below.
+
+.. literalinclude:: /../../../python/examples/basic.py
+   :language: python
+   :lines: 18-48
+
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   structure
+   supported_ops

doc/sphinx/source/python_api/structure.rst

+==================
+nGraph Python APIs
+==================
+
+
+.. autosummary::
+   :toctree: _autosummary
+   :nosignatures:
+
+   ngraph
+   ngraph.exceptions
+   ngraph.ops
+   ngraph.runtime
\ No newline at end of file

doc/sphinx/source/python_api/supported_ops.rst

+============================
+List of operations
+============================
+
+.. currentmodule:: ngraph.ops
+
+.. rubric:: Functions
+
+.. autosummary::
+   :nosignatures:
+
+   absolute
+   acos
+   add
+   asin
+   atan
+   avg_pool
+   batch_norm
+   broadcast
+   ceiling
+   concat
+   constant
+   convert
+   convolution
+   cos
+   cosh
+   divide
+   dot
+   equal
+   exp
+   floor
+   function_call
+   get_output_element
+   greater
+   greater_eq
+   less
+   less_eq
+   log
+   logical_not
+   max
+   max_pool
+   maximum
+   min
+   minimum
+   multiply
+   negative
+   not_equal
+   one_hot
+   pad
+   parameter
+   power
+   prod
+   reduce
+   relu
+   replace_slice
+   reshape
+   reverse
+   select
+   sign
+   sin
+   sinh
+   slice
+   softmax
+   sqrt
+   subtract
+   sum
+   tan
+   tanh
\ No newline at end of file

python/ngraph/ops.py

@@ -825,5 +825,5 @@ def function_call(function_to_call, args):  # type: (Node, NodeVector) -> Node
 
 @nameable_op
 def get_output_element(data, index):  # type: (Node, int) -> Node
-    """Return the `n`th element of the input tuple."""
+    """Return the n-th element of the input tuple."""
     return GetOutputElement(data, index)