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
Choose 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.
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.
If the palette appears nonfunctional, open the Option Inspector
() and check that DynamicUpdating->Automatic
in the Global Preferences
Clicking New Guide Page
brings up a dialog requesting that the title of the new guide be specified.
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.
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.
A sample guide page can be found by clicking Sample Guide Page
near the top of the palette.
Enter some descriptive text describing what the guide covers.
Add links and descriptions for emphasized functions by using the 1 Line Function Listing
button near the top of the 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.
Click 1 Line Function Listing
to automatically create a link.
Less important functions may be listed as function inline listings.
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.
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
Related functions can be organized into groups by placing the cursor between cells and clicking Delimiter
on the palette. Text above each function group may be inserted with the Subsection
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 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 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.
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.