© 2015 IBM Corporation

SPLDOC Enhancements

IBM InfoSphere Streams Version 4.0

Nigel Godwin

Product Development

For questions about this presentation contact Nigel Godwin at

nigelg@us.ibm.com

2 © 2015 IBM Corporation

Important Disclaimer

THE INFORMATION CONTAINED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONALPURPOSES ONLY.

WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THEINFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED “AS IS”, WITHOUT WARRANTYOF ANY KIND, EXPRESS OR IMPLIED.

IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY,WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.

IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OROTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION.

NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED TO, OR SHALL HAVE THE EFFECT OF:

• CREATING ANY WARRANTY OR REPRESENTATION FROM IBM (OR ITS AFFILIATES OR ITS ORTHEIR SUPPLIERS AND/OR LICENSORS); OR

• ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENTGOVERNING THE USE OF IBM SOFTWARE.

IBM’s statements regarding its plans, directions, and intent are subject to change orwithdrawal without notice at IBM’s sole discretion. Information regarding potentialfuture products is intended to outline our general product direction and it should notbe relied on in making a purchasing decision. The information mentioned regardingpotential future products is not a commitment, promise, or legal obligation to deliverany material, code or functionality. Information about potential future products maynot be incorporated into any contract. The development, release, and timing of anyfuture features or functionality described for our products remains at our solediscretion.

THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.

IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION.

3 © 2015 IBM Corporation

Agenda

Introduce SPLDOC to new users

Describe enhancements made for Version 4.0

4 © 2015 IBM Corporation

High-Level Overview

What is SPLDOC?

– SPLDOC provides user API reference documentation for Streams toolkits

– In the form of HTML documentation (DITA format is also available)

Why use SPLDOC?

– To provide good toolkit API documentation for Streams application developers

How to generate documentation– Run the “spl-make-doc” command

– On the required toolkit directories

How to modify the documentation for a toolkit– Add descriptions for the toolkit artifacts (operators, functions, types)

– Use SPLDOC markup to control formatting

– SPLDOC reads from the XML and SPL files in a toolkit

What is SPLDOC markup?– A simple markup

– For formatting headings, paragraphs, lists, etc

– Where the marked up text resembles the intended output

5 © 2015 IBM Corporation

Examples of the generated documentation

Are in the IBM Knowledge Center

– IBM InfoSphere Streams Version 4.0 documentation

– Reference > Toolkits > Specialized toolkits

– Eg, for the ExceptionCatcher operator in the com.ibm.streams.teda toolkit:

6 © 2015 IBM Corporation

Enhancements made for Version 4.0

A single document for multiple toolkits– Using the command: spl-make-doc –t <toolkit-path>

Indexes for operators, functions and types– Across all toolkits

– Within a toolkit

Descriptions for namespaces– In namespace-info.spl files

Option to copy referenced image files to the documentation directory– So the documentation can be relocated

– Using the “—copy-image-files” option

SPLDOC markup for– A hierarchy of pages to describe a single artifact (eg a toolkit or operator)

– Section headings

– Extended nesting of lists

– Embedding of code blocks in lists

– Blank lines in code blocks

7 © 2015 IBM Corporation

Toolkit index

8 © 2015 IBM Corporation

Operator index for a toolkit

9 © 2015 IBM Corporation

Description as a hierarchy of linked pages

10 © 2015 IBM Corporation

Nested lists and code blocks

11 © 2015 IBM Corporation

SPLDOC markup to produce the previous output

Start a new page with a title (use a “+” sign)

Nested lists and code blocks (use “1.”, “*”, and indentation)

12 © 2015 IBM Corporation

Questions?