Authoring Guide Pages Using Documentation Tools
|Setting Up DocumentationTools||Adding Search Index Information|
|Authoring||Leaving Four X's|
|Adding Cross-Links||Preview Button|
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 paclet directory structure for saving and working with documentation using Documentation Tools. To learn more about creating paclets, consult the Creating Paclets tutorial.
Choose Palettes ▶ Documentation Tools from the system menu bar. A 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.
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.
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 paclet's Guides directory.
Add links and descriptions for emphasized functions by using the 1 Line Function Listing button near the top of the Documentation Tools palette. Place the cursor in the part of the cell where the four X's are to the left of description and replace the X's with the function name. Add a short description to the right, typing over description.
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.
Related functions can be organized into groups by placing the cursor between cells and clicking Delimiter on the DocumentationTools palette.
The Tech Notes section is for related tech notes, the More About section is for links to guide pages, and the Related Links section is for other related pages (including webpages).
Choose Links on the Documentation Tools palette and pick the type of link from the column. (Expand More Link Tools for more options.)
"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.
Whenever a cell is left with the content four X's, it will be omitted by the build process. Thus the author need not do anything with such cells.