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 OperatorsDocNAME.xml is not used to map the operator’s key to its name anymore, because I18N does not work with this approach. The name is now defined in the operator’s documentation document you will see next. The following document adheres to the new operator documentation format from that is valid from version 2025.0.0 on. In case you need to document an operator for an older version, please select the appropriate version of this document above.

How the updated OperatorsDocNAME.xml looks like

The updated OperatorsDocNAME.xml now looks like this (the tags of an operator are optional):

<?xml version="1.0" encoding="windows-1252" standalone="no"?>
<operatorHelp lang="en_EN">
    <!--  This is an example how to specify the translation of operator keys to names. -->
    <operator>
      <key>my_own_operator</key>
      <tags>
        <tag>My First Tag</tag>
        <tag>My Second Tag</tag>
      </tags>
    </operator>
    <!-- This is how group keys are translated: -->
    <group>
      <key>operator_test</key>
      <name>Example Group</name>
    </group>
</operatorHelp>

The extension template contains an example of operator documentation. The XML file is placed in the folder NAMESPACE.example_group, where 'NAMESPACE' is the extension's namespace. The namespace can be specified in the build.gradle file. If it is not explicitly defined, it is derived from the extension name (all lower case and blank spaces are replaced with an underscore "_"). You should create one folder, called NAMESPACE.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'.

Pay close attention to the correct paths for the operator documentation files: The mentioned folder is located in src/main/resources/ whereas other resources are mainly located in src/main/resources/com/rapidminer/extension/resources/.

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" name="My own Operator" locale="en"
          version="6.5.000">
        <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 key="input" name="input" type="com.rapidminer.example.ExampleSet">
                Input port description.
            </port>
        </inputPorts>
        <outputPorts>
            <port key="output" 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" name="log text" type="string">
                Description here
            </parameter>
        </parameters>

        <differentiation>
            <!-- ... -->
        </differentiation>

        <tutorialProcesses>
            <tutorialProcess key="log.test" 
                     title="Logging custom text">
                <description>
                    <paragraph>
                        Tutorial description here.
                    </paragraph>
                </description>
                <process version="6.5.000">
                    ...
                </process>
            </tutorialProcess>
        </tutorialProcesses>
    </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.

Adding references to your documentation

You might want to reference the operator's name or other operators in your documentation. To reference the operator's own name, you can use the <operator-ref/> tag somewhere inside description texts (e.g. inside the synopsis text). To reference another operator, use <operator-ref>KEY</operator-ref> with KEY being the key of the operator you want to reference.

That same referencing works for parameters as well, using the <parameter-ref>KEY</parameter-ref> or, if referencing itself within the parameter's description, <parameter-ref/>. If the parameter key contains dots, it must be quoted like this: <parameter-ref>"SOME..KEY"</parameter-ref>.

This referencing also applies to ports, using <inport-ref>KEY</inport-ref> or <outport-ref>KEY</outport-ref> (or, for self reference, <inport-ref/> or <outport-ref/>). If referencing ports of other operators, you can use the combined operator and port key: <outport-ref>other_operator_key.port_key</outport-ref>.

References to parameter values can be done with <value-ref/> if inside the <value>, <value-ref>value_key</value-ref> if inside the <parameter> or <value-ref>parameter_key.value_key</value-ref> in all other places.

You can also reference other parts of the documentation to clarify connections and differences. Just create a list of related documents like so:

<differentiation>
    <relatedDocument key="some_other_document">Some description.</relatedDocument>     
    <!-- ... -->
</differentiation>

Adding a tutorial process

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.

Advanced example

Here's an example, showing you most of the elements described above in action:

<?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" name="My own Operator" locale="en"
          version="6.5.000">
        <synopsis>This is an example Operator. 
              It writes to the Log View when being executed.
        </synopsis>
        <text>
            This operator documentation can refer to itself (<operator-ref/>) and to other operators,
            e.g. <operator-ref>annotate</operator-ref>.
            You are also able to reference other parts of this documentation, e.g. a value from a parameter:
            <value-ref>random seed.varying</value-ref>
        </text>
        <inputPorts>
            <port key="input" name="input" type="com.rapidminer.example.ExampleSet">
                Input port description. A port can reference itself: <inport-ref/>. It can also reference other ports:
                <outport-ref>output</outport-ref>
            </port>
        </inputPorts>
        <outputPorts>
            <port key="output" name="output" type="com.rapidminer.example.ExampleSet">
                Output port description.
            </port>
        </outputPorts>

        <!-- description of the parameters and the corresponding values -->
        <parameters>
            <parameter key="random_multiplier" name="random multiplier" type="int">
                The multiplier that is used to fill the random values (that are generated between 0 and 1).
                A parameter can reference itself (<parameter-ref/>) or other parameters: <parameter-ref>random
                seed</parameter-ref>.
            </parameter>
            <parameter key="random_seed" name="random seed">
                <paragraph>
                    Some description.
                </paragraph>
                <values>
                    <value name="fixed" value="fixed">
                        Some setting to influence the parameter <parameter-ref>random multiplier</parameter-ref>.
                        This value references to itself: <value-ref/>
                    </value>
                    <value name="varying" value="varying">
                        This value references the value <value-ref>fixed</value-ref>
                    </value>
                </values>
            </parameter>
        </parameters>

        <differentiation>
            <relatedDocument key="annotate">Some other operator</relatedDocument>
        </differentiation>

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

Next steps

Congratulations on your first complete operator, repeat steps 3 through 6 of this guide for each operator 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