Making Documentation with DocGen

Here’s a quick example of how we can use some of the stuff I showed in this post to build out full documentation by hand.

‌

Getting DocGen

This post will be using my DocGen system which is built into a large package of mine that supports other parts of the development process as well. This package lives in a paclet on my paclet server. You can install it with:

PacletInstall["BTools",
 "Site"->""
 ]

If you want to learn more about making paclet servers you can read more here .

‌

Documenting the Templating system

We’re going to make use of a palette I designed for helping with the documentation system. After you’ve installed BTools you can open it by looking for BTools▸DocGen in the palettes menu:

Palette Overview

The entire palette looks like this:

If we look at it, it essentially has five sections:

The first of these chooses the paclet and lets us open the relevant config files. The second lets us open any built documentation pages for this context. The third actually generates the content and optionally deploys it to the cloud. The fourth will make documentation indices for pre version 11.2 and the last creates a new documentation paclet.

Creating a new Documentation Paclet

We start off by making a new paclet to hold our documentation. To do that we just use the button. It pops up a window:

And we simply provide the name of our paclet. The current project will then switch to "Templating" :

And we see the paclet info and config file have been built:

Making a SymbolPage Template

First we go to the "Context Pages" menu and select "Symbol Page Template"

This opens up a notebook with templates for all the symbols in the context:

Making a Symbol Page

We can fill out the content for a page:

And then we use the docked cell on the template page to build out the HTML (with the bracket for the content we’re generating selected):

This then builds a doc page for us:

Saving a Symbol Page

Alternately we can do this from the palette using the "Generate and Save" menu to save the page to the current paclet:

And then if we go to the "Open Symbol Page" menu we see we’ve generated and saved the page:

Making Multiple Pages

Alternately, if we opted not to select a cell bracket the package will generate a page for every template in the InputNotebook . Or if we had selected multiple brackets pages would be generated for each. This gives us a way to easily update our documentation from a saved template. Here’s what we get if we did it with no bracket selected:

Deploying the Paclet

The DocGen palette doesn’t directly support deploying this paclet to a server, but we can use the Paclet Server Manager palette that also comes with BTools to do that. I won’t go into the details, though, as they’re documented here .

Generating HTML Documentation

We can also use these template to build HTML documentation. To do this without deployment we can simply select the "Symbol Web Pages" action from the "Generate from Notebook" menu (again with the bracket selected):

This builds to a temporary directory (it also mirrors the display assets it needs the first time it’s generated). The Cloud Deploy option comes into play when using the "Generate and Save" menu.

After this copies every thing and generates the HTML we end up with a page that looks like:

Which of course looks like the 11.0 docs, but until a new version of "Transmogrify" and "DocumentationBuild" come out this is what we’re restricted to. That, unfortunately, is outside of my control so we’ll stop at this.