Adding Your Documentation
to Mathematica 6

André Kuzniarek

Document Systems Manager
Wolfram Research

Quick introduction to DocuTools

Working from existing material

Working from scratch

Using Workbench 1.2 to create, build, and deploy documentation

Quick introduction to DocuTools

DocuTools Alpha:
http://download.wolfram.com/?key=BVN5T1

Review of palette views

Review of primary features

Working from existing material

Splitting ref guide into function pages

Splitting user documentation into tutorials

Working from scratch

Set this variable if needed:

(* $DocuToolsDir= *)

An example of symbols as a test run:

Names["*Solve*"]

CreateDocument@FunctionPageForSymbol[#]&/@Take[Names["*Solve*"],5];

Using Workbench 1.2 to Create, Build, and Deploy Docs

Beta to become available shortly,
contact Wolfram Technical Support

Windows Alpha:
http://download.wolfram.com/?key=GKFQUL

Macintosh Alpha:
http://download.wolfram.com/?key=JLBTU8

Sample package documentation:
http://download.wolfram.com/?key=EANQCJ

Outline of working process (detailed instructions w/beta)

Start Workbench and accept the suggested base working directory.

Preferences > Mathematica > Paclet Development > 
"Configure Mathematica for Developing Documentation".

File > New Project > Paclet Project:
"NumericalAnalysis" — name is important to match URIs in links

Go to "English" directory in sample and copy from there to same directory in Workbench package explorer view.

Ignore the PacletInfo.m file in sample, it's there for reference.
Workbench creates it automatically when starting a new project.

From this point, changes should be managed through paclet info editing pane.

Double-click on the PacletInfo.m file to open that pane.

Click on "Documentation" tab.

Use this view to add/move/rename files.
Open the Guide folder, set "Set Main Guide" to set as root.
Save paclet.m!

Try the actual build process before actually adding any new files

Under Window > Show View > Documentation Build Tools.

Select project, then "Create Build", which generates docbuild.xml.

Select "Run Build". 

Test within Mathematica as a child process.

Opens the M help viewer directly at your guide page because of setting "Main Guide".

"Captive" help viewer works for any pages in paclet, they are formatted as in-product documentation. Also, see "Installed Add-ons" to see your project listed.

Back in Workbench, go to HTML files and double click to view.

Subdirectory without -HTML extension contains in-product docs.
Drop this in $UserBaseDirectory/Autoload and package is loaded in M.
Only on Windows currently, fixed for all other platforms in M 6.0.2.

After creating a new function page in paclet editor view, double-click to open in M slave and to use Palettes > DocuTools for continuing with edits and updates.

DocuTools edits source notebooks, for structuring and formatting use by the documentation build tools to deploy  in-product and web docs. Source notebooks use different stylesheets than the in-product docs, and the styles do not all correspond 1-to-1. It's not impossible to do you own processing and editing of notebooks in the final in-product format, but DocuTools is not designed to support that.