Authoring Symbol Pages Using Documentation Tools

1.  Choose Palettes ▶ Documentation Tools from the system menu bar. A palette will appear on the right side of the screen. Select the F tab at the top of the palette for function page authoring tools.

2.  When authoring paclet documentation for the first time with Documentation Tools, the paclet location will need to be configured. Click Add Paclet ... near the palette's top and navigate to and choose the top directory of your paclet. This will activate the links in the authoring notebooks for testing purposes. If you have not already created a paclet documentation directory structure, then when a new paclet is added Documentation Tools will automatically create the directory Paclet Name > Documentation > Language and the directories Guides, ReferencePages, and Tutorials inside the Language directory. Additionally, the Symbols directory will be created inside the ReferencePages directory. By default, Language will be the English name for your chosen Wolfram System language, and will typically match

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.

Usage and Templates

1.  Clicking New Function Page brings up a dialog requesting that the name of the new function be specified.

2.  Once that is done, clicking OK will construct a new function page with the symbol name and metadata already filled in. In addition, the function page will be saved in the project's Symbols directory.

3.  Fill out the function template and add a corresponding usage message.

4.  Highlight the function template and click Template Input on the Documentation Tools palette.

The Template Input dialog will appear. Select the top radio button and click OK to format the selection as a symbol in the package. This is the preferred formatting for your function template and any occurrences of your package function names in the authoring notebooks.

Individually highlight the inputs for the function in the usage message ("m" and "n" in this example) and select Template Input. The Template Input dialog will again appear. Select the bottom radio button and click OK to format the selection without linking to any package. This is the preferred formatting for the inputs for your functions.

The final result should resemble:

5.  To add another function template with usage, move the cursor to the end of the current usage message and click Double Usage Line on the Documentation Tools palette.

6.  The result will look like:

Follow the same procedure mentioned above to add a new template and usage message.

Note: Template Input should be used to format any references to the function or its inputs anywhere in your documentation notebook.

Note: Template Input should also be used to format any references to Wolfram Language functions. However, as these functions are built into the Wolfram Language, a dialog will not appear when Template Input is clicked.

Notes and Options Tables

1.  The Notes section of the notebook directly below the tan usage cell is for documenting options, common uses, implementation syntax for different results, etc. Use the Template Input button as above to format and link symbols and format templates in notes cells.

Enter an options table by placing the cell insertion bar above or below a notes cell and doing one of the following:

• If you have already written a package (.wl) file, select Notes ▶ Options Table on the Documentation Tools palette. This will automatically load your package, and open a dialog listing Options that have been defined for the current symbol. In the dialog, check the options you want to include, add descriptions in the input fields, and click Insert.

• If not, position your cursor between cells where you want to insert an options table, click Insert Custom Table to insert a table with a number of rows that you specify, and in the resulting dialog choose 3 Column and click OK. Otherwise, in the select Notes ▶ Table Tools section of the Documentation Tools palette, select the
  button to insert a 3-column code input table. Use the Add Row button to add rows as needed. For each option and value, you will need to highlight it, select Links > Link to Function, select the upper radio button from the dialog that appears, and click OK. The options go in the left column, default settings (or values) in the middle column, and a short description in the right column.

2.  To link to other guides, tutorials, or symbols in the paclet, highlight the text, select Links on the Documentation Tools palette, and choose the appropriate link destination.

Examples

1.  Since the functions in the paclet are not part of the Wolfram Language, a Needs statement is required to load them. The Examples Initialization section can be used to run initialization code that is used by every example. By default, the Examples Initialization section will contain an appropriate Needs statement for loading the primary package declared by the current paclet. The cell containing the Needs statement is unevaluatable and the style definition for "Input" is set up to make use of the content of the Needs statement whenever an "Input" cell is evaluated on a function page.

Navigate to the Basic Examples section in the authoring notebook and place the cell insertion bar just below the header. By default, typing in the Basic Examples section will create new code input cells. Use Examples ▶ Insert Text on the Documentation Tools palette to insert text that describes the functionality an example is demonstrating. Each group of related examples should be separated by a delimiter, which can be added by selecting Examples ▶ Insert Delimiter.

Note: The most effective examples introduce a single new feature of a function. Crowding examples together with multiple options can make it difficult for users to determine what each of the options does.

2.  Examples can also be added in the More Examples section using the same procedure mentioned above.

• You can manually add subsections for each header.

• If you have already written a package (.wl) file, click Examples ▶ Options for Function on the Documentation Tools palette to add subsubsections for each option.