Creating Documentation with Wolfram Workbench

© Wolfram Research, Inc.

Course Contents

Getting Wolfram Workbench™

Configuring Workbench

Creating documentation pages

Building the documentation

Deploying the application

Getting Wolfram Workbench

To build documentation for your application you will need to install:

Eclipse IDE for Java (SE) or Java EE developers

(http://www.eclipse.org/downloads/eclipse-packages)

Mathematica 10+

Wolfram Workbench plugin for Eclipse

(http://support.wolfram.com/kb/27221)

The application icon for Eclipse  will be added to your computer, and the Wolfram Workbench icon  will be seen only within the Eclipse IDE.

Configuring Wolfram Workbench

To create documentation, your package files (.m and .wl) must live in Workbench.

If you have an existing project, you can import it into Workbench.

If you have never used Workbench for a project, start a new one from File ▶ New ▶ Other.

From the list of choices, pick Wolfram and click the triangle on the left. Choose Application Project.

Give your project a name, click Next and check the Create PacletInfo.m checkbox.

When you click Finish, you will get a choice to have the project always open in the Wolfram Language Development environment.

Connecting to Mathematica

For each project, you will need to select the Mathematica® application that will run it.

Open Eclipse ▶ Preferences and select Wolfram.

Click the Add button and browse the folder structure to locate the version of Mathematica you wish to use.

Click Apply and OK.

The Wolfram Workbench Layout

The Wolfram Workbench layout is shown below.

Note: You can select the Wolfram Language Development perspective from Window ▶ Perspective ▶ Open Perspective ▶ Other ... ▶ Wolfram Language Development.

The various views in the default perspective include:

the main editing window (where you write your code)

outlines (package outline, editor outline, etc.)

the console (where information about Mathematica evaluations is displayed)

Note: If you do not see the console, you can bring it up from Window ▶ Show View ▶ Other ▶ General ▶ Console.

Configuring PacletInfo.m

The PacletInfo.m file contains the instructions for Mathematica to set file paths and establish links. If the file is not configured correctly, some parts of the documentation will fail.

When you click the PacletInfo file (from the Package Explorer), an Overview wizard is displayed. The wizard allows you to edit the application creation details.

Clicking the tabs at the bottom of the wizard switches the editor to the PacletInfo.m file. For the documentation to work correctly, you will need to add two items to the Extensions segment.

The two extensions that need to be added are for “Kernel” and “FrontEnd”.

Creating Documentation Pages

The Details: In Case You Wondered

The documentation pages are created by Mathematica, working with Apache Ant. Mathematica uses the PacletInfo.m file to establish file paths and links. Mathematica is unaware of the code in the Workbench editor until Mathematica is run in Workbench. This is done by selecting a notebook from the application files, right-clicking and selecting Run as Wolfram. This uses Get or Needs to load the file into the Mathematica kernel. Mathematica can then identify the functions defined in the package context and using the build tools, can create documentation page templates.

Cells in the templates, where the cell contents are "XXXX", will be ignored in the build process. For this reason, it is important to modify the templates carefully to avoid having unwanted cells in the final documents. You can use the PacletInfo/Documentation tab in Workbench to have the program build the templates for you.

Once you have all the templates filled out, you can use link at the bottom of the PacletInfo window (except for the PacletInfor.m editor) to open the build tools. There, you can select the project name and click the Build button to have Ant build the documentation.

The Steps

Create templates

Fill in the templates

Run the build (Ant)

Deploy the application

Creating the Templates

A good place to start is with a guide page. Select Guides and click the AddPage button. This will bring up a dialog where the name of the guide page can be given.

Your first guide page would typically be set as the Main page. This is the page that will display if someone searches for your application package in the documentation. Tutorials are required to create an Overview page.

Clicking Create Symbol Pages will bring up a dialog where you can select the function pages you want. The dialog window presents checkboxes to have the program complete the templates from the application.

Clicking the OK button creates the function page templates, and they will show under the Symbols section.

The documentation templates will also be listed in the package outline view.

Filling in the Details

It is suggested that you look at some of the documentation pages in Mathematica and use them as a model for organizing your documentation. This is not mandatory, but makes it easier to create the pages for your application.

The Documentation Tools include a palette that helps in formatting the documentation pages. In general, you will have fewer problems if you use the palette to insert text, links and additional lines in function usage panels.

Here are some examples:

Adding a link to a documentation page.

Select the left-hand side and choose Link to Symbol. Links will have the form paclet:Polynomials/ref/DerivativePlot.

DerivativePlot -> paclet:Polynomials/ref/DerivativePlot

All input should be evaluated. The build process does not evaluate the notebook.

You can get an idea of what each of the buttons in the palette does by looking at the tooltip associated with the button.

Note: You may need to add the path of the Eclipse installation directory to the list of trusted directories in Mathematica for the Documentation Tools palette to work properly. You can do this from the Preferences ▶ System tab, by clicking Edit Trusted Directories ▶ Add and then browsing and selecting the Eclipse installation directory to add it to the list of trusted directories.

Building the Documentation

({{, }})

Deploying the Application

To deploy the application, together with the documentation:

Click the Deploy Application button in the Application Tools view.

In the wizard, select the files you want to include and select the location for the package.

The next panel will include the necessary files for the documentation.

Click Finish.

To distribute the application to other users, choose Archive. This will produce a .zip file that can be burned to disk or distributed for download.