A symbol page (also called a function page) focuses on a single function or option, providing its different input templates with corresponding usage description, additional notes including the function's options, if any, and a set of examples. Sections are provided to link to other related documents.
The material below assumes that you have already set up an appropriate paclet directory structure for saving and working with documentation using Documentation Tools. To learn more about creating paclets, consult the Creating Paclets tutorial.
Below, a paclet called Example will be used, with PublisherID JohnDoe.
Setting Up DocumentationTools
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.
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 $Language.
Authoring
If you clicked F > Tools > Generate Function Pages (having already written one or more .wl files and positioned them in the MyPaclet/Kernel/ directory with a corresponding "Kernel" extension), most of the fields described below will already contain content in the proper formatting, with the exception of the examples, which will still need to be written.
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
Clicking New Function Page brings up a dialog requesting that the name of the new function be specified.
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.
Fill out the function template and add a corresponding usage message.
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:
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.
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
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 Details & Options▶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.
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.
Adding Cross-Links
Authoring notebooks have several sections devoted to different cross-references. The Tech Notes section is for links to related tutorials, the Related Links section is for other related pages (including webpages), the See Also section is for links to other function pages, and the Related Guides section is for links to guide pages.
Start typing in any section to add text. Then make a selection, click Links on the Documentation Tools palette and pick the type of link from the column. (Expand More Link Tools for more options.)
The suggested conventions are as follows. For all sections excluding the See Also sections, cross-links should appear in separate cells.
The See Also section is typically arranged in a horizontal inline listing orientation. Under the See Also section, enter a list of function names (which may be symbols from your application or Wolfram Language symbols). The list may extend over a number of lines.
Then highlight the cell bracket and click Inline Listing Toggle near the top of the Documentation Tools palette. Documentation Tools will create the links and inline listing structure automatically. If you later want to add more functions to the list, select the cell bracket and click Inline Listing Toggle. The function list will again be plain text. Add more function names and then click Inline Listing Toggle again.
Examples
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.
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.
Adding Search Index Information
Scroll to the bottom 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 Wolfram Documentation.
Leaving Four X's
Whenever a cell is left with the content 4 X's, it will be omitted by the build process. Thus the author need not do anything with such cells. Rows in a table whose elements are all 4 X's will be omitted by the build process. In addition, tables whose elements are all 4 X's will likewise be omitted.
Preview Button
At the top of the authoring notebook is a Preview button.
Clicking the Preview button generates a built version of the authoring notebook.
