[Py] (Partially) automatic generation of python API doc (#973)

* 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

* FIX: Disable autogeneration of summary files in documentation.

* Remove redundant file containing duplicate information.

* Remove unused Sphinx extensions.

* (Partially) automatic generation of python API doc.

- Detailed documentation is generated automatically
- Summaries are generated automatically for all files except runtime.py
  which is parsed incorrectly.
- No additional steps required. Only run `make html`. Under the hood there
  is lunched script which generates all required files to some temporary
  directory under `/tmp/sphinx_auto_py_doc/` and copied to docs directory
  afterwards.
- Remove `autosummary_generate` from in configuration file since we use
  custom script which performs this step.

* Review update.

* Automatically generated stub files for doc.

- Added just few empty lines which has been removed during recent merge.

doc/sphinx/Makefile

@@ -29,7 +29,7 @@ clean:
 	@rm -rf ../doxygen/latex
 	@rm -rf ../doxygen/*.tmp
 
-doxy-code:
+doxy-code: gen_python_api_doc
 	$(Q)(cat ngraph.doxyfile ; echo "STRIP_FROM_PATH=${NGRAPH_BASE}" ) | doxygen -  2>&1 | tee doc.log
 
 html: doxy-code
@@ -124,4 +124,5 @@ coverage:
 	@echo "Testing of coverage in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/coverage/python.txt."
 
-
+gen_python_api_doc:
+	@./generate_python_api_doc.sh

doc/sphinx/generate_python_api_doc.sh

+#!/usr/bin/env bash
+
+###############################################################################
+# 
+# This script generates stub files for automatically generated documentation
+# of the nGraph Python API.
+# 
+###############################################################################
+
+# paths relative to this file location
+NGRAPH_REPO=../..
+DOC_DIR=${NGRAPH_REPO}/doc
+TMP_DIR=/tmp/sphinx_auto_py_doc
+EXCLUDE_DIRS="${NGRAPH_REPO}/python/ngraph/impl*
+              ${NGRAPH_REPO}/python/ngraph/utils*"
+CURRENT_DIR=.
+
+cd ${NGRAPH_REPO}/python/ngraph
+PYTHONPATH=. sphinx-autogen -t ${DOC_DIR}/sphinx/source/_templates/ -o ${TMP_DIR} \
+                             ${DOC_DIR}/sphinx/source/python_api/structure.rst
+sphinx-apidoc -f -M -d 1 -T -o ${TMP_DIR} ${CURRENT_DIR} ${EXCLUDE_DIRS}
+
+rm ${TMP_DIR}/ngraph.runtime.rst
+cp ${TMP_DIR}/* ${DOC_DIR}/sphinx/source/python_api/_autosummary/
+
+rm -rf ${TMP_DIR}

doc/sphinx/source/_templates/autosummary/module.rst

+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+
+   .. rubric:: Functions
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+
+   {% block classes %}
+   {% if classes %}
+
+   .. rubric:: Classes
+
+   .. autosummary::
+     :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+
+   {% block exceptions %}
+   {% if exceptions %}
+
+   .. rubric:: Exceptions
+
+   .. autosummary::
+     :nosignatures:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/sphinx/source/conf.py

@@ -36,8 +36,6 @@ needs_sphinx = '1.6.5'
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.inheritance_diagram',
-    'sphinx.ext.graphviz',
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
@@ -218,10 +216,3 @@ rst_epilog = u"""
 # -- autodoc Extension configuration --------------------------------------
 
 autodoc_mock_imports = ['ngraph.impl', 'ngraph.utils']
-
-# -- autosummary Extension configuration ----------------------------------
-
-# This enables autogeneration of standard summary files
-# However we customize them to our needs, thus disable it at the moment.
-
-# autosummary_generate = ['python_api/structure.rst']

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

-=================
 ngraph.exceptions
 =================
 
 .. automodule:: ngraph.exceptions
 
+   
+   
+   
+
+
+   
+   
+   
+
+
+   
+   
+
    .. rubric:: Exceptions
 
    .. autosummary::
+     :nosignatures:
    
       NgraphError
       NgraphTypeError

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

-==========
 ngraph.ops
 ==========
 
 .. automodule:: ngraph.ops
 
+   
+   
+
    .. rubric:: Functions
 
    .. autosummary::
       :nosignatures:
-
+   
       absolute
       acos
       add
@@ -66,3 +68,15 @@ ngraph.ops
       sum
       tan
       tanh
+   
+   
+
+
+   
+   
+   
+
+
+   
+   
+   
\ No newline at end of file

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

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

doc/sphinx/source/python_api/index.rst

@@ -16,6 +16,7 @@ of the API usage below.
 
 .. toctree::
    :maxdepth: 1
+   :titlesonly:
 
    structure
-   supported_ops
+   List of operations <_autosummary/ngraph.ops.rst>

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