Documentation Tools Quick Start

1.gif

Add Paclet Choose the directory of the paclet you are developing documentation for. The directory specified can be empty, it can just have a PacletInfo.m or PacletInfo.wl file, or it can in addition have files and directories making up a paclet that can be loaded and whose functions can be called. More information can be found in Configure a Paclet for Use with Documentation Tools.
Paclet Inspector Displays a table of paclet names referenced in PrivateFrontEndOptions/"InterfaceSettings"/"DocumentationTools". The Paclets Inspector also displays the current paclet; the directory paths of referenced paclets; their load states and documentation directories existence states; and buttons for opening the paclet directories and changing their locations, as well as buttons to load referenced paclets and create documentation directories for referenced paclets not having them.
Functions (F) Tab
New Function Page (?) Start a new function page. Use the ? notch button to open a sample function page.
Open Function Page Opens a dialog displaying links for all function pages (in the currently selected paclet) whose names start with or contain a given substring.
Template Input Select a function template. Lowercase words (with one or more letters) in function templates become italic after the template input button is used. xxx$yyy makes yyy a subscript of xxx. $$ gives (\[Ellipsis]). Function names will become links when appropriate. Refer to the Format menu for the Template Input shortcut (Documentation Tools custom menu items are in brackets).
Double Usage Line Use this to insert a new usage message template and explanatory text placeholder after the cursor position in a function page usage cell.
Inline Listing Toggle Toggles formatting back and forth between plain text and an inline listing with links and formatted delimiters appropriate for the cell the selection is in. Insertion between cells creates a See Also listing template. Use . to indicate delimiters between function names.
For information about creating function pages, see Generate Function Pages.

Details & Options

Note Insert a notes cell or apply the notes style to selected cells.
Options Table Dialog: select options corresponding to a function page's name to insert as a table into the notes area of a function page.

TableTools

1 Col/1 Text Insert a onecolumn table.
2 Col/2 Text Insert a twocolumn table.
3 Col/3 Text Insert a threecolumn table.
Add Row
Sort Table Sorts on the first column of a table.
Merge Tables
Span First Column
Insert Custom Table (2/3 column)

Examples

Insert Delimiter This divides example groups and resets the input history.
Insert Text
Insert Needs Inserts a Needs statement with the context found in the metadata of the input notebook. Attempts to load the paclet specified by the paclet specified in the metadata.
Section/Subsec/Subsub
Options for Function Compares the current listed options in the Options section of a function page to those returned by Options for the function being documented. A dialog lets you select any missing options to add.

Links

Link to Guide () Creates a guide page link of the selection. The notch button opens a file browser for a file to be linked from your selection as a guide page link.
Link to Tech Note () Creates a tech note link of the selection. The notch button opens a file browser for a file to be linked from your selection as a tech note link.
Link to Function () Creates a function page link of the selection. The notch button opens a file browser for a file to be linked from your selection as a function page link.
Link to URL Dialog to insert a URL to be hyperlinked from the selection.
Edit Link Dialog to edit the contents of a link if it cannot be edited inline. Place the cursor after the link before applying.

More Link Tools

Make Sel/Make Link Make Sel creates a link to the selected cell and saves the data in a form that can be used by the button to the right of this one. First select a cell in a saved notebook, then use the button to the right of this one to make selected text in a notebook into a link using the data obtained. Make Link inserts a link over the selected text. Use the Make Sel button first.
Link to Document Browse your paclet layout for a notebook to be linked from your selection. This relies on $ApplicationName, and target documents can reside in the directories ReferencePages/Symbols, Guides or Tutorials under Documentation/$Language.
Custom URI Creates a link based on the paclet URI you provide interactively.

Formatting

Special Formatting A palette of additional input forms.
Default Format Returns the default format of the current cell while typing, or removes formatting on the selection.
Literal Input Use this for literal Wolfram Language input format in text. Same as doing +9 (for inline cells).
Code Inline Use this for code or other computer voice elements inline in text.
Italic Input Use this to make italics in function templates only (e.g. for function arguments).
Plain Text Use this to make plain text in function templates only (e.g. for function arguments).
Traditional Math Use this to begin or apply an approximation to the traditional mathematical notation.
Annotate (, , D) Dialog for annotating a cell or editing a cell's annotation. searches down in the input notebook for the next annotation cell. searches up in the input notebook for the next annotation cell. D remove a cell's annotation.

Futurize

Selection Set status of a selected cell to be excluded from documentation builds. Button toggles setting on/off.
Whole Page Set status of the input notebook so that it will be excluded from documentation builds. Button toggles setting on/off.

Tools

Generate Function Pages Generate function pages for all symbols with usage messages in the current paclet. Any existing notebooks are placed in the OriginalReferencePages directory within the ReferencePages/Symbols directory.
Rename Symbol Rename a symbol in all documentation notebooks of the current paclet. Does not modify code files. Replaces instances of the symbol in metadata, links, instances of the symbol in inline cells and input cells.
Replace Paclet Base Change the paclet name, context and URI in metadata as well as the link base used in button data in all notebooks in a paclet's documentation directories.

Other

Settings Opens the Documentation Tools settings dialog for setting an author username, specifying whether or not to display a fill out a metadata reminder message when starting a new documentation page and whether or not open page dialogs should close when links to pages are clicked.
Help
Guides (G) Tab
New Guide Page (?) Start a new guide page. Use the ? notch button to open a sample guide page.
Open Guide Page Opens a dialog displaying links for all guide pages (in the currently selected paclet) whose names start with or contain a given substring.
1Line Function Listing Select between cells to insert a oneline function template. Toggles between formatted and unformatted states when used on or in text of a preexisting oneline function cell.
Functions Inline Listing Use . to delimit elements. Function names will be autolinked. Toggles format on/off for easy editing. Multiple cell brackets may be selected.
Subsection
Delimiter Item separator for function listing area.
GuideText
For more information about creating guide pages, see Create a New Guide Page.

Links

Formatting

Futurize

Tools

Other

Tech Notes (T) Tab
New Tech Note Page (?) Start a new tech note page. Use the ? notch button to open a sample tech note page.
Open Tech Note Opens a dialog displaying links for all tech notes (in the currently selected paclet) whose names start with or contain a given substring.
Section
Subsection
Text
Example Group Insert an example group.
Example Caption Insert an example caption.
For more information about creating tech notes, see Create a New Tech Note.

Definition Boxes

2 Column Inserts a two-column definition box.
3 Column Inserts a three-column definition box.
Add Row Adds a row to a definition box.
Merge Combines two selected definition box cells into one cell.

Links

Formatting

Futurize

Overview Tools

Generate Overview Create an overview page of a selected list of tutorial files.
New Overview Page
TOCChapter Insert a TOCChapter cell or apply style to a cell.
TOCSection Insert a TOCSection cell or apply style to a cell.
TOCSubsection Insert a TOCSubsection cell or apply style to a cell.
TOCSubsubsection Insert a TOCSubsubsection cell or apply style to a cell.

TOC Link Tools

(1) Browse Browse for a tech note to link to its headings.
(2) Select Cell Select a cell bracket in the browsed-for tech note and then click this button.
(3) Paste Click a cell bracket or between cells in the overview being constructed and then click this button.

Tools

Other