Providing Operator Documentation

It's natural to add documentation to program code, but this does not help the end user who never sees any part of the program code.

You have already configured the files OperatorsNAME.xml and OperatorsDocNAME.xml to provide the operator with an icon and name.

The extension template contains an example of operator documentation. The XML file is placed in the folder NAME.example_group, where 'NAME' is the extension name. You should create one folder, called NAME.group_name, per operator group, and add one XML file per operator to the respective group folder.

../img/documentation-folder-structure.png

In this example, the folder is named mytest.operator_test, because the extension name is 'MyTest' and the group ID is 'operator_test'. The file is called my_own_operator.xml, because the operator key is 'my_own_operator'.

Now, copy the sample file content and adapt it to your needs:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../../../../../
    rapidminerreferencemanual/documentation2html.xsl"?>
<p1:documents xmlns:p1="http://rapid-i.com/schemas/documentation/reference/1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://rapid-i.com/schemas/documentation/reference/1.0 ">

    <operator key="operator.mytest:my_own_operator" locale="en"
          version="6.5.000">
    <title>My own operator</title>
    <synopsis>This is an example Operator. 
          It writes to the Log View when being executed.
    </synopsis>
    <text>
        <paragraph>First paragraph.</paragraph>
        <paragraph>Second paragraph.</paragraph>
    </text>
    <inputPorts>
        <port name="input" type="com.rapidminer.example.ExampleSet">
            Input port description.
        </port>
    </inputPorts>
    <outputPorts>
        <port name="output" type="com.rapidminer.example.ExampleSet">
            Output port description.
        </port>
    </outputPorts>

    <!-- description of the parameters and the corresponding values -->
    <parameters>
        <parameter key="log_text" type="string">
            Description here
        </parameter>
    </parameters>

    <tutorialProcesses>
        <tutorialProcess key="log.test" 
                 title="Logging custom text">
            <description>
                <paragraph>
                    Tutorial description here.
                </paragraph>
            </description>
            <process version="6.5.000">
                ...
            </process>
        </tutorialProcess>
    </tutorialProcesses>

    <relatedDocuments>
        <!-- ... -->
    </relatedDocuments>
    </operator>
</p1:documents>

Change the content between the tags to describe your operator, ports and parameters.

Don’t forget to adapt the operator key in this document. Otherwise, your operator icon will not display correctly in the operator help.

You can add a tutorial process. To do so, complete the tutorial description and exchange the process tags with the process XML of your tutorial process.

How to extract a process XML

Build the Altair RapidMiner process that you want to add to the documentation.
Then, open the View > Show Panel > XML menu. The XML panel opens.
Move the XML panel to a comfortable place in Altair AI Studio. You can see the process in XML format in the panel.
Copy the complete XML code to extract the process.

Congratulations for your first complete operator, repeat steps 3 through 6 of this guide for each operator that you want included in your extension.

Then, publish your extension if you want to provide it to the Community or check out which advanced enhancements you can build for Altair AI Studio.

Categories

Versions

Providing Operator Documentation