Creating documentation for sub-packages in Workbench

Question

I'd like to create proper documentation for a package of mine, and Workbench in principle provides the tools to do this. However, I've split my package into multiple sub-packages (because I found it easier to maintain the code that way), structured as follows:

mainPackage`
           `myPackage`
                     `subPackage1`
                     `subPackage2`
                     `subPackage3`

The documentation tools in Workbench are set up in such a way that, out of the box, they only work with one top-layered package. For instance, the Create symbol pages button from the Documentation tab in the PacletInfo.m editor only looks for symbols within the context \$ApplicationName (which you can set in the Overview tab of the PlacletInfo.m editor), and it's not possible for $ApplicationName to have quotes (`).

So my question is: does anyone have a workaround for this? I could merge all my subPackages into myPackage, but unfortunately it won't be possible to remove the top-layer mainPackage.

Answer 1

After some tinkering, I found an acceptable solution.

The first step is to simply structure the application project in Workbench such that the top package mainPackage is not there, and merge all the sub-packages into myPackage. After building the package and documentation, which then more or less works out of the box, I can then place the package inside the mainPackage directory, such that the final directory structure will be

$(User)BaseDirectory/
    Applications/
        mainPackage/
            myPackage/
                PacletInfo.m
                code.m
                Kernel/
                    init.m
                Documentation/
                    English/
                        ...

However, the problem now is that Mathematica can't find the documentation, because the myPackage directory is not directly in $(User)BaseDirectory but in the subdirectory mainPackage. Thus we need to tell Mathematica to look for subpackages in the directory mainPackage. One way to do this is to include the following in the code of myPackage:

PacletManager`PacletDirectoryAdd[
    FileNameJoin[{$UserBaseDirectory, "Applications", "mainPackage"}]
];
PacletManager`RebuildPacletData[];

This is sufficient for the documentation to show up in the Documentation Center.