Incremental build in Workbench 2 Is it possible?

Question

I am developing a package which currently has 129 symbols and 13 tutorials. Each time I run a build WB takes about 11 minutes to build the documentation files. Each time I make a small change in just one of the symbol pages or in one tutorial, I need to run a Build.

Is it possible to "build" only some (selected) pages (symbol or tutorial) of the documentation, without having to rebuild everything else?

Answer 1

It is possible, but first, I am not sure if what I describe below is the only way (or even the simplest one), and second, the procedure described below might lead to an inconsistent index, so use it only for a quick test. This will also require some ( very basic) familiarity with Apache Ant.

The documentation build is performed by running Apache Ant (from within WorkBench) on the build file docbuild.xml, which is auto-generated by the build tools (which you see when you open the PacletInfo.m), and is normally located at the root of your WB project. To get a feel for it, you can right-click on this file and choose Run-As->Ant Build. There will be 2 choices, the first will run the default build target, and the second will allow you to pick which build targets you want to run. You can pick the first one, and what you should see is exactly the same output as you see normally when you run the build from the PacletInfo.m editor (build tools).

Here are the steps of the suggested procedure then:

• Make a copy of the docbuild.xml (call it mydocbuild.xml, or any other way you like), and put it to the same root project folder.
• Create a folder (say in the root project folder), with the name you like, say MyDocBuild.
• Copy to that folder the full structure of the current documentation source folder Documentation->English->... (basically, copy the Documentation folder in full).
• In that copied Documentation folder, remove all files which you don't want to build. In the future, you just put there the files you want to build currently, possibly programmatically (this step can be later further automated. If you are familiar with Ant, you can create another Ant target to do that. Or, you could write a Mathematica script to populate this folder from Mathematica).
• Left-click on the file mydocbuild.xml (or whatever name you use for it), to open it in the WB editor - you will have to edit it.

• In the second line:

  <project name="BuildDocumentation" default="main" basedir=".">"
  

  change the default target from "main" to "docbuild".

• Locate the line

  <property name="inputDir" value="${basedir}/${docInputDir}" />
  

  in the build file, and change it to

  <property name="inputDir" value="${basedir}/MyDocBuild/Documentation" /> 
  

  where I assumed that you named your directory holding documentation sources for an alternative build as MyDocBuild.

• Save your changes

Now, you should be all set to make your builds. From the above steps, only populating the alternative documentation folder with files wil have to be performed every time when you want to add more files to the build or remove some. Other steps have to be done only once.

To make a build, you will have to perform the same procedure as already described:

• Left-click on mydocbuild.xml (or, right-click, if you click from the edit area of this file)
• Choose Run-As->Ant Build (first choice. Since we changed the default target to docbuild, you don't have to pick it explicitly)

As I said, I do not suggest this as a replacement for the full build, but rather just as a quick way to "prototype" your documentation. You will have to perform a full build to be sure that everything (cross-links, index, etc) will work properly.