Merge pull request #1366 from ddebrunner/toc_docs_1

Remove toc from modules and signatures from autosummaries.
IBMStreams · Dec 21, 2017 · d3b900b · d3b900b
2 parents c4fda97 + e4013f7
commit d3b900b
Show file tree

Hide file tree

Showing 14 changed files with 67 additions and 51 deletions.
diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/ec.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/ec.py
@@ -4,11 +4,6 @@
 """
 Access to the IBM Streams execution context.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.ec
-
 Overview
 ########
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/rest.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/rest.py
@@ -3,8 +3,8 @@
 # Copyright IBM Corp. 2016,2017
 
 """
-Python API that wraps the REST apis for IBM® Streams
-& IBM Streaming Analytics service on IBM Bluemix®.
+REST API bindings for IBM® Streams
+& IBM Streaming Analytics service on IBM Cloud.
 
 Streams REST API
 ################
@@ -36,6 +36,9 @@
     `Streaming Analytics REST API <https://console.ng.bluemix.net/apidocs/220-streaming-analytics?&language=node#introduction>`_
         Reference documentation for the Streaming Analytics service REST API.
 
+Module contents
+###############
+
 """
 
 import os

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/rest_primitives.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/rest_primitives.py
@@ -1,6 +1,21 @@
 # coding=utf-8
 # Licensed Materials - Property of IBM
 # Copyright IBM Corp. 2016,2017
+
+"""
+Primitive objects for REST bindings.
+
+Overview
+########
+
+Contains classes representing primitive Streams objects, such as
+:py:class:`Instance`, :py:class:`Job`, :py:class:`PE`, etc.
+
+Module contents
+###############
+
+"""
+
 import logging
 import requests
 import queue

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/op.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/op.py
@@ -4,11 +4,6 @@
 """
 Integration of SPL operators.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.spl.op
-
 Invoking SPL Operators
 ++++++++++++++++++++++
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/spl.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/spl.py
@@ -4,11 +4,6 @@
 """
 SPL Python primitive operators.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.spl.spl
-
 Overview
 ========
 SPL primitive operators that call a Python function or

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/toolkit.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/toolkit.py
@@ -5,11 +5,6 @@
 """
 SPL toolkit integration.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.spl.toolkit
-
 Overview
 ########
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/types.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/spl/types.py
@@ -4,11 +4,6 @@
 """
 SPL type definitions.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.spl.types
-
 Overview
 ########
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/context.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/context.py
@@ -5,11 +5,6 @@
 
 Context for submission of applications.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.topology.context
-
 Overview
 ========
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/schema.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/schema.py
@@ -4,11 +4,6 @@
 """
 Schemas for streams.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.topology.schema
-
 Overview
 ========
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/tester.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/tester.py
@@ -6,11 +6,6 @@
 
 Testing support for streaming applications.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.topology.tester
-
 Overview
 ========
 

diff --git a/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/topology.py b/com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/topology.py
@@ -5,11 +5,6 @@
 """
 Streaming application definition.
 
-.. toctree::
-   :maxdepth: 4
-
-   streamsx.topology.topology
-
 Overview
 ########
 

diff --git a/python/sphinx/.gitignore b/python/sphinx/.gitignore
@@ -1,2 +1,2 @@
 build
-source/generated
+source/streamsx.*.rst
diff --git a/python/sphinx/source/_templates/streamsx_module.rst b/python/sphinx/source/_templates/streamsx_module.rst
@@ -0,0 +1,40 @@
+{{ 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 %}
+
diff --git a/python/sphinx/source/index.rst b/python/sphinx/source/index.rst
@@ -24,7 +24,8 @@ use of existing IBM Streams toolkits.
 See :py:mod:`~streamsx.topology`
 
 .. autosummary::
-   :toctree: generated
+   :toctree: .
+   :template: streamsx_module.rst
 
    streamsx.topology
    streamsx.topology.topology
@@ -51,7 +52,8 @@ SPL (Streams Processing Language) is a domain specific language for streaming
 analytics supported by Streams.
 
 .. autosummary::
-   :toctree: generated
+   :toctree: .
+   :template: streamsx_module.rst
 
    streamsx.spl.spl
 
@@ -65,7 +67,8 @@ service through HTTPS REST APIs.
 ========
 
 .. autosummary::
-   :toctree: generated
+   :toctree: .
+   :template: streamsx_module.rst
 
    streamsx.rest
    streamsx.rest_primitives