Package documentation separately from code

Question

Mathematica documentation is heavy duty stuff. Of the 7.75GB my Mac says Mathematica 11.3 takes up, 5.46 of that is documentation.

So when I write my own packages I don't want to do what WRI did and bloat my system with docs that will most likely never be opened.

How can I distribute my documentation separately from my program? Can I distribute it in such a way that I can easily push updates?

Answer 1

The trick here is to make a paclet for just your documentation that won't ever interfere with your main package.

To do we'll assume we have a main paclet named "MyPaclet". Then we'll generate its documentation and put it into a new paclet called "Documentation_MyPaclet". This name is chosen to imitate the way the ServiceConnect framework names its paclets (as well as many other internal frameworks).

Then to make sure that it loads when we ask for "MyPaclet" we'll reassign the "LinkBase" argument in the "Documentation" extension to be "MyPaclet", as this is how the Documentation`ResolveLink performs its lookups.

So overall our "PacletInfo.m" will look like:

Paclet[
 Name -> "Documentation_MyPaclet", 
 Version -> "1.0.0", 
 Extensions -> 
  {
    {
      "Documentation", 
      "Language" -> "English", 
      "LinkBase" -> "MyPaclet", 
      "MainPage" -> "Guides/MyPaclet"
      }
    }
  ]

Now when we search for the paclet it will show up, but it won't interfere with PacletFind and it won't interfere with loading the paclet. For instance, using some documentation I auto-built:

PacletFind["Documentation_BTools*"]

PacletFind["BTools"]

What makes this particularly nice, though, is that I can put these paclets on a paclet server and then people can download just what they want for documentation--and if I update the documentation it's easy for these updates to mirror.

For instance, if you wanted to install some of my documentation, you could run:

PacletInstall["Documentation_BToolsWeb",
 "Site"->"http://www.wolframcloud.com/objects/b3m2a1.docs/DocumentationServer"
 ]

And then you can search for BToolsWeb and look at just the part of my documentation that handles web functions in my main package.

If you wanted to update it, you could run:

PacletUpdate["Documentation_BToolsWeb",
 "Site"->"http://www.wolframcloud.com/objects/b3m2a1.docs/DocumentationServer"
 ]

And if you wanted to uninstall it so it doesn't bloat your system you can run:

PacletUninstall["Documentation_BToolsWeb"]