spldoc enhancements for ibm infosphere streams v4.0
TRANSCRIPT
© 2015 IBM Corporation
SPLDOC Enhancements
IBM InfoSphere Streams Version 4.0
Nigel Godwin
Product Development
For questions about this presentation contact Nigel Godwin at
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?