7
$\begingroup$

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?

Improve this question
$\endgroup$
1

1 Answer 1

Reset to default
3
+50
$\begingroup$

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

Improve this answer
$\endgroup$
14
  • $\begingroup$ Thanks for the wonderful information! I went ahead and copied the two files from the Build folder into the folder containing the actual project. But, the documentation appears not to successfully appear in the Documentation Center. (hitting F1 on one of the functions doesn't find it). Also, when I manually open the Guide page--either from the one generated by Workbench or the copied one--, none of the links work: they all seem to point to some empty guide file). The only time these links work is if I view the guide exclusively using 'Preview' within Workbench. Any ideas? Many thanks! $\endgroup$
    – QuantumDot
    Nov 19, 2014 at 11:10
  • $\begingroup$ Make sure to restart kernel after copying files. $\endgroup$
    – jkuczm
    Nov 19, 2014 at 12:00
  • $\begingroup$ @QuantumDot If it doesn't help, make sure that you have following structure: <dirOn$Path>/<appName>/Documentation,<dirOn$Path>/<appName>/PacletInfo.m. If you hover over link in documentation page, it should show the URI in lower left corner, something like paclet:<appName>/ref/<SymbolName> make sure it corresponds to URI in "Categorization" section of source notebook. $\endgroup$
    – jkuczm
    Nov 19, 2014 at 12:07
  • $\begingroup$ Thanks for your response (indeed I have restarted the kernel, and also the whole Mathematica program); also I have the directory structure as you say. And, when I hover over the links in the guide page, I do see the paclet: path, and they all match the one appearing under "Categorization" in the original source file. But it still doesn't work. Something I find very puzzling is that although it all works ok when I "Preview" it using Workbench, none of the links work when I open (with Mathematica) the very same Guide page notebook. Do I need to "Deploy Application" for this to work? $\endgroup$
    – QuantumDot
    Nov 19, 2014 at 12:19
  • $\begingroup$ "Deploy Application" basically copies needed files to desired folder or archive file, so it should work like manual copying. But sure you can try, maybe there's some subtlety that we're missing. $\endgroup$
    – jkuczm
    Nov 19, 2014 at 12:27

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.