Documentation Build like Wolfram Workbench

[lynchs61]

Building documentation for a paclet is tedious at best and I've never been able to successfully do it with anything other than Wolfram Workbench. It would be great if we could have similar functionality in this plugin because Eclipse really sucks compared to Intellij.

I have no idea if this is possible or how to go about it but I figured at least a discussion would be worth it.

[halirutan]

Over the years, I talked many times about this issue with different people. I'll give you the summary:

1. Building docs is only possible within WB and all tools needed for that (e.g. the Docu-Tools palette) are packed inside. As third-party developer, I cannot simply steal things from there. It would be unlawful and I would always be on the shady side, even if Wolfram doesn't take action.

2. The whole building process is undocumented and highly fragile, especially if you want to build documentation that works on several versions of Mathematica. IIRC, it consists of an ant script which builds the indices and structure required to incorporate package documentation into the help-browser.

3. Even though Mathematica's documentation itself is one of the best I've ever seen for a product like this, I would describe the process of building it "company-internal experts only" in its current state.

I highly recommend that you watch this Twitch stream that was recorded only 2 months ago. It's basically the first time that I saw a public proposal to document and update the documentation tools.

This video contains many funny highlights. For instance at around minute 27 it becomes clear that even the docu tools veterans don't know everything. It starts with

I'm going to do something I had never thought I would do which is point out something good about the docu-tool...

So in summary: If there is in the future an official way how to build documentation, I will, of course, consider adding it. At the moment, however, it doesn't look like Wolfram is there.

[szhorvat]

@lynchs61 All that said, can you clarify what you are looking for?

Building documentation for a paclet is tedious at best

It is literally a single click in Workbench. What exactly is the issue? Are you just looking to avoid starting Workbench at all? Or is it some other problem with the documentation tools?

[lynchs61]

@szhorvat Yes I'm looking to avoid workbench completely. Basically to have the same process for building documentation in workbench, in Intellj with this plugin. Aside from the fact that I use the Jetbrains tools everyday so I'd rather not have to use a different IDE, I also just think Intellj is a much better product than eclipse. So it would be nice if paclet building could be completely done (including documentation) in Intellij.

[halirutan]

I'll leave this open as a feature request, but don't expect a solution in the near future. First WRI needs to provide an official specification of how to build documentation with a Wolfram Kernel only. In the worst case, they consider other solutions like building it into the front end without the possibility to start it from a different process.

[alecGraves]

Maybe the new Paclet functions could be used to automate this, though they seem pretty easy for users to just use as functions.