Merge pull request #1362 from ddebrunner/toc_docs_1

Add initial autosummary setup.

com.ibm.streamsx.topology/opt/python/packages/streamsx/ec.py

@@ -2,14 +2,23 @@
 # Licensed Materials - Property of IBM
 # Copyright IBM Corp. 2017
 """
-Overview
---------
 Access to the IBM Streams execution context.
 
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.ec
+
+Overview
+########
+
+This module (`streamsx.ec`) provides access to the execution
+context when Python code is running in a Streams application.
+
 A Streams application runs distributed or standalone.
 
 Distributed
------------
+===========
 Distributed is used when an application is submitted
 to the Streaming Analytics service on IBM Bluemix cloud platform
 or a IBM Streams distributed instance.
@@ -21,7 +30,7 @@
 resources (hosts) in the Streams instance.
 
 Standalone
-----------
+==========
 Standalone is a mode where the complete application is run
 as a single PE (process) outside of a Streams instance.
 
@@ -30,7 +39,7 @@
 .. _streams_app_log_trc:
 
 Application log and trace
--------------------------
+#########################
 
 IBM Streams provides application trace and log services.
 
@@ -76,8 +85,9 @@
 Application code must not modify the root logger, if additional handlers or different levels are required a child logger should be used.
 
 Execution Context
------------------
-This module (`streamsx.exec`) provides access to the execution
+#################
+
+This module (`streamsx.ec`) provides access to the execution
 context when Python code is running in a Streams application.
 
 Access is only supported when running:
@@ -90,6 +100,9 @@
 Most functionality is only available when a Python class is
 being invoked in a Streams application.
 
+Module contents
+###############
+
 """
 
 import enum

com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/op.py

@@ -2,6 +2,13 @@
 # Licensed Materials - Property of IBM
 # Copyright IBM Corp. 2016,2017
 """
+Integration of SPL operators.
+
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.spl.op
+
 Invoking SPL Operators
 ++++++++++++++++++++++
 
@@ -111,6 +118,9 @@
     `Operator invocations <https://www.ibm.com/support/knowledgecenter/en/SSCRJU_4.2.0/com.ibm.streams.ref.doc/doc/operatorinvocations.html>`_
          Operator invocations from the SPL reference documentation.
 
+Module contents
++++++++++++++++
+
 """
 
 import streamsx.topology.exop as exop

com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/spl.py

@@ -2,6 +2,13 @@
 # Licensed Materials - Property of IBM
 # Copyright IBM Corp. 2015,2017
 """
+SPL Python primitive operators.
+
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.spl.spl
+
 Overview
 ========
 SPL primitive operators that call a Python function or
@@ -527,6 +534,10 @@ def myfunc(a,b):
 can contain a mix of valid values.
 
 The list may be empty resulting in no tuples being submitted.
+
+Module contents
+===============
+
 """
 
 from enum import Enum

com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/context.py

@@ -1,12 +1,25 @@
 # coding=utf-8
 # Licensed Materials - Property of IBM
 # Copyright IBM Corp. 2015,2017
-"""Context for submission of applications.
+"""
+
+Context for submission of applications.
+
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.topology.context
+
+Overview
+========
 
 The main function is :py:func:`submit` to submit
 a :py:class:`~streamsx.topology.topology.Topology`
 to a Streaming Analytics service or IBM® Streams instance for execution.
 
+Module contents
+===============
+
 """
 from __future__ import print_function
 from __future__ import unicode_literals

com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/schema.py

@@ -4,10 +4,22 @@
 """
 Schemas for streams.
 
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.topology.schema
+
+Overview
+========
+
 On a structured stream a tuple is a sequence of attributes,
 and an attribute is a named value of a specific type.
 
 The supported types are defined by IBM Streams Streams Processing Language (SPL).
+
+Module contents
+===============
+
 """
 from __future__ import (absolute_import, division,
                         print_function, unicode_literals)

com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/tester.py

@@ -2,7 +2,17 @@
 # Licensed Materials - Property of IBM
 # Copyright IBM Corp. 2017
 
-"""Testing support for streaming applications.
+"""
+
+Testing support for streaming applications.
+
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.topology.tester
+
+Overview
+========
 
 Allows testing of a streaming application by creation conditions
 on streams that are expected to become valid during the processing.
@@ -76,6 +86,10 @@ def test_filter(self):
 
 .. warning::
     Python 3.5 and Streaming Analytics service or IBM Streams 4.2 or later is required when using `Tester`.
+
+Module contents
+===============
+
 """
 
 import streamsx.ec as ec

com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/topology.py

@@ -3,8 +3,12 @@
 # Copyright IBM Corp. 2015,2017
 
 """
-Python API to allow creation of streaming applications for
-IBM® Streams & Streaming Analytics service on Bluemix.
+Streaming application definition.
+
+.. toctree::
+   :maxdepth: 4
+
+   streamsx.topology.topology
 
 Overview
 ########
@@ -163,6 +167,9 @@ def __exit__(self, exc_type, exc_value, traceback):
 
 See :py:mod:`streamsx.spl.op`
 
+Module contents
+###############
+
 """
 
 from __future__ import unicode_literals

python/build.xml

@@ -17,29 +17,9 @@
   </target>
 
   <target name="pythondoc_work" if="${topology.build.sphinx}">
-   <mkdir dir="${py.doc}"/>
-   <exec executable="sphinx-apidoc"
-         dir="${sphinx.dir}" failonerror="true">
-     <arg value="--separate"/>
-     <arg value="-o"/>
-     <arg value="source"/>
-     <arg value="${streamsx.py.dir}"/>
-
-     <!-- excluded packages -->
-     <arg value="${streamsx.py.dir}/streamsx/st.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/spl/runtime.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/condapkgs.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/dependency.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/exop.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/functions.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/graph.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/param.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/runtime.py"/>
-     <arg value="${streamsx.py.dir}/streamsx/topology/splpy_setup.py"/>
-   </exec>
-
    <exec executable="make"
          dir="${sphinx.dir}" failonerror="true">
+     <arg value="clean"/>
      <arg value="html"/>
    </exec>
    <copy todir="${py.doc}">

python/requirements.txt

@@ -0,0 +1,4 @@
+requests
+future
+dill
+enum34

python/sphinx/.gitignore

@@ -0,0 +1,2 @@
+build
+source/generated

python/sphinx/source/conf.py

@@ -33,9 +33,13 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.napoleon'
 ]
 
+autodoc_default_flags = ['members']
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -100,7 +104,7 @@
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+modindex_common_prefix = ['streamsx.', 'streamsx.spl.', 'streamsx.topology.']
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False

python/sphinx/source/index.rst

@@ -3,22 +3,72 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+##########################
 IBM Streams Python support
-==========================
+##########################
 
-.. automodule:: streamsx
+Python APIs for use with IBM® Streaming Analytics service on
+IBM Bluemix® cloud platform and on-premises IBM Streams.
 
+**********************************
+Python Application API for Streams
+**********************************
 
-Contents:
+Module that allows the definition and execution of streaming
+applications implemented in Python.
+Applications use Python code to process tuples and tuples are Python objects.
 
-.. toctree::
-   :maxdepth: 2
+SPL operators may also be invoked from Python applications to allow
+use of existing IBM Streams toolkits.
 
-   source/modules.rst
-   source/streamsx.rst
-   source/streamsx.spl.rst
-   source/streamsx.topology.rst
+See :py:mod:`~streamsx.topology`
 
+.. autosummary::
+   :toctree: generated
+
+   streamsx.topology
+   streamsx.topology.topology
+   streamsx.topology.context
+   streamsx.topology.schema
+   streamsx.topology.tester
+   streamsx.topology.tester_runtime
+   streamsx.ec
+   streamsx.spl.op
+   streamsx.spl.types
+   streamsx.spl.toolkit
+
+******************************
+SPL primitive Python operators
+******************************
+
+SPL primitive Python operators provide the ability
+to perform tuple processing using Python in an SPL application.
+
+A Python function or class is simply turned into an SPL primitive operator
+through provided decorators.
+
+SPL (Streams Processing Language) is a domain specific language for streaming
+analytics supported by Streams.
+
+.. autosummary::
+   :toctree: generated
+
+   streamsx.spl.spl
+
+***********************
+Streams Python REST API
+***********************
+
+Module that allows interaction with an running Streams instance or
+service through HTTPS REST APIs.
+
+========
+
+.. autosummary::
+   :toctree: generated
+
+   streamsx.rest
+   streamsx.rest_primitives
 
 Indices and tables
 ==================