11
$\begingroup$

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?

$\endgroup$
  • $\begingroup$ Does such a package exist whose documentation is so huge that you wouldn't want to install it? $\endgroup$ – QuantumDot Mar 22 '18 at 0:19
  • 1
    $\begingroup$ @QuantumDot documentation can easily balloon in size as packages bloat and the number of symbols increases. I figure it's only kind to any people who choose to use my packages to keep them free of bloat that could be served separately on demand. In a non-object-oriented language if you document each function and each documentation page is at minimum 50 kb it only takes 150 symbols to reach ~10MB of docs. And reaching 150 symbols is easy unless you're careful about your design. $\endgroup$ – b3m2a1 Mar 22 '18 at 0:25
  • 3
    $\begingroup$ Oh ok. Usually, the problem I have with other people's packages is quite the opposite -- definitely not enough documentation. $\endgroup$ – QuantumDot Mar 22 '18 at 0:28
  • $\begingroup$ @QuantumDot that's why I've been working on a system to autogenerate docs :) And that makes documentation bloat even easier... $\endgroup$ – b3m2a1 Mar 22 '18 at 0:29
11
$\begingroup$

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*"]

enter image description here

PacletFind["BTools"]

enter image description here

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"]
$\endgroup$
  • 5
    $\begingroup$ We do this also, for example with FEMDocumentation. It is still shipped with Mathematica, but it is structured as a Documentation-only paclet. So it could in principle be shipped separately, or updated separately, etc... $\endgroup$ – Itai Seggev Mar 22 '18 at 0:17
  • $\begingroup$ @ItaiSeggev I'd really love if more documentation were loaded in an on-demand fashion. Particularly for stuff like the "Units" package where the package is already deprecated (of course the heavy hitter is the system-level docs anyway) $\endgroup$ – b3m2a1 Mar 22 '18 at 0:19
  • 1
    $\begingroup$ @ItaiSeggev Is it technically feasible to make the FE be able to read gzipped notebooks? If would result in a very significant saving on the documentation size. $\endgroup$ – Szabolcs Jul 9 '18 at 20:12
  • $\begingroup$ @Szabolcs that’d be great. Python does something like that for compressing modules. $\endgroup$ – b3m2a1 Jul 9 '18 at 21:05
  • $\begingroup$ @Szabolcs It would have certain costs. A notebook has structure that allows the FE the only loaded the rough outline, and load other parts on demand as you scroll/open sections. Gzip would essentially destroy that strucutre, so the FE would need need to either unzip the whole notebook and look at the copy, or read in the whole notebook at opening time. Either would lead to a significant delay in opening notebooks. $\endgroup$ – Itai Seggev Jul 11 '18 at 6:15

Your Answer

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

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