Documentation Tools Package Tutorial

Authoring Guide Pages Using DocumentationTools

A guide page focuses on a single topic, providing links to functions that share functionality. Sections are provided to link to other related documents.

The material below assumes that you have already set up an appropriate directory structure for saving and working with documentation using the DocumentationTools package. If you are working from Workbench it will already have been done. Otherwise, with "MyApplication" representing the name of your application, create the directory structure MyApplication > Documentation > English and the directories Guides, ReferencePages, and Tutorials inside the English directory. Then create the directory Symbols within the ReferencePages directory.

Setting Up DocumentationTools

1. Choose Palettes ► DocumentationTools from the Mathematica menu bar. A gray palette will appear on the right side of the screen. Select the G tab at the top of the palette for guide page authoring tools.

2. If you are not starting Mathematica from a project within Workbench, you will need to configure DocumentationTools. Click Set PacletName & Path near the palette's top and navigate to the English directory of your application. This will activate the links in the authoring notebooks for testing purposes.

Note: If the palette appears nonfunctional, open the Option Inspector (Format ► Option Inspector) and check that DynamicUpdating->Automatic in the Global Preferences.

Authoring

1. Clicking New Guide Page brings up a dialog requesting that the title of the new guide be specified.

2. Once that is done, clicking OK will construct a new guide page with the title and metadata already filled in. In addition, the guide page will be saved in the project's Guides directory. The dialog that comes up is informational and may be permanently dismissed if so desired.

Out[5]=

Note: The authoring notebooks contain a series of placeholders that will not be included with the build unless you explicitly edit them. These placeholders will typically contain four X's.

Note: A sample guide page can be found by clicking Sample Guide Page near the top of the DocumentationTools palette.

3. Enter some descriptive text describing what the guide covers.

4. Add links and descriptions for emphasized functions by using the 1 Line Function Listing button near the top of the DocumentationTools palette. Place the cursor in the part of the cell where the gray X's are and replace XXXX with the function name. Be careful not to type over the inline cell. Add a short description to the right.

5. Click 1 Line Function Listing to automatically create a link.

6. Less important functions may be listed as function inline listings.

7. List individual function names in place of XXXX. Any number of functions may be included in a list. Each pair in the list should be separated by a space, then a period, and then another space. If you want to include a link to a symbol in another application, include it as otherlinkbase/ref/symbol, where otherlinkbase is usually the other application's name.

8. With the cursor in the cell or at the cell bracket, click Functions Inline Listing. If you later want to add more functions to the list, select the cell bracket and click Functions Inline Listing. The function list will again be plain text. Add more function names and then click Functions Inline Listing again.

9. Related functions can be organized into groups by placing the cursor between cells and clicking Delimiter on the DocumentationTools palette. Text above each function group may be inserted with the Subsection button.

Adding Cross-Links

The Tutorials section is for related tutorials, the More About section is for links to guide pages, and the Related Links section is for other related pages (including web pages).

Start typing in any section to add text. Then make a selection, choose Links on the DocumentationTools palette, and pick the type of link from the column. (Expand More Link Tools for more options.)

Adding Product Artwork

Click Insert Artwork Banner Cell on the DocumentationTools palette and follow the instructions to add product branding artwork to the guide page.

Adding Search Index Information

Scroll to the top of the authoring notebook and expand the Keywords cell group.

"Keyword" cells are what the Mathematica search index uses when cataloging the authoring notebooks, and are not case-sensitive.

Keywords are set up to return the page in the list of search results if a user were to search for that word in the Documentation Center.

Leaving XXXX

Whenever a cell is left with content XXXX, it will be omitted by the build process. Thus the author need not do anything with such cells.