There are interactive examples in the documentation in Wolfram Mathematica. Thus to compile them we just need Shift+Enter. I want to develop such examples for functions from my own package, how can I do this?

Thanks a lot for comments..I use W. Workbench 2.0 to build documentation. But here is the problem, while building, even the examples like NumericalAnalysis it failed with errors:


C:\Documents and Settings\NumericalAnalysis\docbuild.xml:132: The following error occurred while executing this line:

C:\Documents and Settings\NumericalAnalysis\docbuild.xml:97: The following error occurred while executing this line:

C:\Program Files\Wolfram Research\WolframWorkbench\2.0\configuration\org.eclipse.osgi\bundles\10\1.cp\MathematicaSource\DocumentationBuild\SystemFiles\ant\Build\notebook.xml:71: Failed to launch or connect to Mathematica kernel: Connected MathLink program has closed the link, but there might still be data underway.

Total time: 3 seconds

If anyone has any suggestions, please , write!!


migrated from stackoverflow.com Jun 10 '12 at 1:50

This question came from our site for professional and enthusiast programmers.

  • $\begingroup$ I couldn't get Workbench to work properly as long as I had umlauts in the path. Maybe your path/directory contain non-standard characters. $\endgroup$ – Markus Roellig Jun 13 '12 at 9:49

This answer is intended to be progressively updated as I gain experience with this functionality myself. I assume you are using Wolfram Workbench and the documentation authoring tools it provides.

As the documentation describes, you need to make sure that your package(s) are in a proper directory structure for a Mathematica application. You can do this by initially selecting "Application" for the project type in Workbench. (File > New > Project) enter image description here

If you already have packages, you need to move them into this structure, at the top level folder for the project. (I have obscured the project name here so as not to identify my employer.)

enter image description here

Right-click/control-click on one of the subfolders in the documentation folder tree, and choose New > Notebook File.

enter image description here

Once created you can right-click on that file to open in Mathematica. When Mathematica is launched in this way, it will include in the Pallettes menu an item for Documentation Tools.

enter image description here

From this you can click on the Utilities button to reveal the Generate Function Pages button. Clicking this will generate fresh documentation pages for all the functions and options defined in your package. It is also clever enough to trace through if your main package calls other custom packages and creates documentation for those objects as well. My current project has around 60 new functions and options; it took about three minutes to create all the pages.

However, for this to work well, it is essential that you have already defined good usage messages for all your functions and options defined in your packages. Usage messages have to start with the name of the function to be recognised properly: see the example in the screenshot below.

enter image description here

The pages themselves come out looking like this:

enter image description here

Obviously, in this instance, my DateListBarChart function builds on existing functionality and takes all the options that BarChart does.

If you scroll down these pages, you will find that they have sections designed specifically for examples that you can provide, and that the user can interact with.

enter image description here

To get the documentation into final form, you need to click the Build button in the Application Tools tab of Workbench’s Mathematica Development perspective. You can then click Deploy Application in the same tab to get package and bundle into a place on the $Path that Mathematica can find when it is running normally rather than in conjunction with Workbench.

enter image description here

Most of this information is in the Workbench documentation, but to be honest it isn’t particularly clear. The tip about making sure you have sensible usage messages wasn’t anywhere that I could find.

  • $\begingroup$ I noticed when creating documentation with this tool that copying examples from the example pages available from the Author palette for each kind of available document type (Symbol,Guide,Tutorial) is usually faster than adding new elements with buttons from the Author palette. $\endgroup$ – faysou Jun 11 '12 at 20:34
  • $\begingroup$ @Verbeia I followed your steps but got BUILD FAILED: /Users/admin/Documents/workspace/test/docbuild.xml:90: taskdef A class needed by class com.wolfram.jlink.util.MathematicaTask cannot be found: org/apache/tools/ant/Task using the classloader AntClassLoader[/Applications/Mathematica.app/Contents/SystemFiles/Links/JLink/JLink.jar] $\endgroup$ – M.R. Dec 12 '16 at 17:28

Take a look at Wolfram Workbench 2 and its documentation. They demonstrate how to set up help pages similar to the built in ones.


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy