Merging documentation from Workbench with package coded outside Workbench

Question

On the one hand, I have been writing my package (directly into the .m file) separately using the standard Mathematica front-end. My source .m files and the init.m files have the appropriate folder structure to make the package work by simply running << myPackage` It all works very nicely.

On the other hand, I am building the complete documentation of this package with Wolfram Workbench 2.0. The intention is that when I'm finally done, somehow I could manually take all the documentation files generated by Workbench, and put it into the same folder where I've been developing my actual package. Then hopefully the documentation would be properly integrated into the documentation center, and I can distribute this folder to others. However, after writing up the documentation for a handful of functions (which apparently is a ton of work), I realized how flimsy Workbench is, and I am beginning to feel that most likely I am not going to be able to figure it out in the end because there appears to be so much going behind the scenes every time I "Build" the documentation [and there is also a "Deploy Application" button which I'm scared of pressing].

What are the steps to integrate the documentation generated by Wolfram Workbench with a pre-existing package? In particular, which files do I need to move into the package directory? Do I need to be careful about the name given to the project in Workbench? What if the various functions in the package have been defined in different sub-pacakges (different sub-contexts)? Would it still work?

Answer 1

What are the steps to integrate the documentation generated by Wolfram Workbench with a pre-existing package? In particular, which files do I need to move into the package directory?

When you build documentation, Workbench puts all files needed for documentation deployment in build directory inside your project (if you didn't modify automatically generated docbuild.xml file). There should be at least two files in build/<appName> directory: PacletInfo.m and Documentation directory. Copying them to directory containing your pre-existing application should be enough.

Do I need to be careful about the name given to the project in Workbench?

When creating "application project" (and that's what you want to build documentation) creation wizard asks several questions. "Project name" is irrelevant for documentation, but in third step you're asked for "Application details" this is the relevant part. Make sure "Application name" is the same as name of your pre-existing package. Also check "Create PacletInfo.m" and "Create documentation".

What if the various functions in the package have been defined in different sub-pacakges (different sub-contexts)? Would it still work?

Yes, it will work, but make sure that symbols have correct context set in "Categorization" section of source documentation notebooks.

Alternative

Since, as you noticed, there is much going on behind the scenes in process of creating documentation. It might be easier not to copy documentation to pre-existing package outside of workspace, but to copy the pre-exsting package into your Workbench project.

When your package is inside "application paclet project" you can double click on PacletInfo.m file. It will open Paclet editor in which, in Documentation tab, you can automatically create stub pages for all public symbols of your package.

You will be also able to easily deploy your whole application, together with documentation, using Deploy Application button, mentioned in the question.

Deploying application

To deploy application one needs to copy application directory (containing package files, PacletInfo.m and Documentation folder with built notebooks) to desired directory.

To be able to load package context with standard Needs["myPackage`"], make sure that directory, to which application was copied, is on Mathematica $Path.

To be able to use documentation, make sure that directory, to which application was copied, is one of "paclet directories".

$UserBaseDirectory/Applications/ and $BaseDirectory/Applications/ by default meet both criteria. If you want to deploy application to other directory you can evaluate:

PrependTo[$Path, "path/to/dir"]
PacletDirectoryAdd["/path/to/dir"]

First line adds directory to $Path and second adds it to "paclet directories". PacletDirectoryAdd is undocumented function from PacletManager` context, it works in all Mathematica versions that I have available i.e. 8.0, 9.0 and 10.0.

Further reading

• Integrating notebooks to Mathematica's documentation center
• How to work with Application Project files in Wolfram Workbench?
• What is a Mathematica Application?