Message Boards Message Boards

GROUPS:
Mathematica Wolfram Language Packages User Interface
Martijn Froeling

DocumentationTools in version 13.0: creating documentation from usage

Martijn Froeling, University Medical Center Utrecht
Posted 24 days ago
561 Views
|
5 Replies
|
15 Total Likes
|

With the introduction of the new DocumentationTools in Mathematica 13 I would love to generate my documentation with the new tools since workbench has been getting too annoying to use.

I have been experimenting with the new tools and functionality. However I have came along an issues that the documentation that is generated automatically from the Function::usage is not properly formatted which was the case in the old DocumentationTools.

When I create a paclet with

CreatePaclet["test2"]

And then add some usage notes

BeginPackage["test2`"]

(* Declare your package's public symbols here. *)

SayHello::usage = "SayHello[x, y] message 1 with x and y."

SayHello1::usage = "SayHello1[x, y] message 1 with x and y.
SayHello1[x, y, n] message 1 with x and y and n."

SayHello2::usage = "SayHelloBla[x, y] message 1 with x and y.
SayHelloBla[x, y, n] message 1 with x and y and n."

Begin["`Private`"]

End[] (* End `Private` *)

EndPackage[]

i can now add this paclet to the new documentation tools.

enter image description here

and the usage notes can be called when the package is loaded.

enter image description here

If I create a new function page for one of the functions using the button "New Function Page" or automatically generate all function pages using "Tools">"Generate Function Pages" the templates generated are not correct. For the three Function::usage I had defined only the first is properly formatted. The moment when multiple variants are defined all goes wrong. Furthermore, in the previous version, I would get a warning in the 3rd case that the usage text is not starting with the correct function name.

enter image description here enter image description here enter image description here

With the pages generated, I can now build the packet however the 2nd and 3rd are not formatted correctly.

enter image description here

with the build from the workbench, I did always get proper formatting and splitting of multiple usages for the same function.

enter image description here

The same way it looks for the build-in documentation.

enter image description here

I have been digging into the DocumentationTools.m file where I guess the magic happens and did see some changes to AuxiliaryCreateReferencePages which I guess is the function called to generate the pages. However, I have not been able to figure out what is going wrong.

For small projects one could fix the layout, however, I usually build a few hundred documentation files when releasing new versions. Has anyone encountered the same issue or knows of a quick fix other than waiting for a new update?

Thanks, Martijn
POSTED BY: Martijn Froeling
Answer
5 Replies
Sort By:

Hi Martijn,

Thanks for bringing this to our attention. I'm managing development on DocumentationTools, so I'll make sure this gets fixed in a coming update. While fixing it, if there's a straightforward workaround, we'll attach it here so you don't have to wait for an official update.

Thanks again!
POSTED BY: Brian Van Vertloo
Answer

Hi Brian,

Thanks for the response!

If I may, I have two additional questions:

  1. Is there any possibility to expose the functions under the pallet to the frontend? I was trying to figure out how I can script the functionality of the "generate function pages" button. Since life is too short for clicking buttons :p... With the new documentation and build tools, I was hoping to have a script that can do an automated weekly build of my packets and automatically push them to git.
  2. Are there plans to convert the documentation to HTML which was (partly) possible with Workbench (with some fixes). That way the documentation can be integrated into my website as I currently do (QMRITools documentation) although being with a very outdated look.

Keep up te great work! Martijn

POSTED BY: Martijn Froeling
Answer

Sorry -- it took longer than I intended to get back to you.

In the near term, you can work around the usage formatting issue by not using newlines in the usage message. We're going to handle that in an update coming soon, but if you make the entire usage message on one line (simply put a space between the end of the first and start of the second template), it should do the right thing.

Re: your other questions, we've recently gotten other feedback about exposing the DocumentationTools functions for programmatic use; I'm considering it. Making them top-level functions comes with an implicit understanding that they're integrated with the language more widely among other things, and we weren't developing with that specifically in mind, so this might be a gradual process.

The documentation build code that is shipping with the desktop products is capable of building HTML pages already, believe it or not. The relevant function is PacletDocumentationBuild (https://reference.wolfram.com/language/PacletTools/ref/PacletDocumentationBuild.html), where you use:

Needs["PacletTools`"];PacletDocumentationBuild[paclet, outdir, "HTML"]

Hope this helps -- let us know if you have other issues!
POSTED BY: Brian Van Vertloo
Answer

This definitely helps! Will try it asap and let you know how things work out. Thanks for the feedback!
POSTED BY: Martijn Froeling
Answer
Andrew Meit
Andrew Meit
Posted 13 days ago

Brian, In the process of figuring out how to parse apart the original System` Symbols usage by using the function Information (and later WolframLanguageData) definitions I discovered many boxes formatting bugs (reported) and inconsistent handling of subscripts (v1 or v_1, and reported). Further, I have formally requested, that a function with several different usage definitions be returned as a list not a large text block that may or may not parse well into single usage statements. Generally, I see the meta-template:

fname[arguments] usagetext. fname[arguments] usagetext. etc...

and the sometimes problematic

fname[arguments] usagetext.\nusagetext. fname[arguments] usagetext.\nusagetext.

Parsing for ". " marker can be brittle since its 2 chars not a single unique glyph marker; ". " would need to be enforced when a definition is created and saved. Can the case be made, unless am missing something, for the following, as consistent even for code use (as long as the dev does not use ; in their usage definition), if a single text block is wanted:

fname[arguments] usagetext.;usagetext\nfname[arguments] usagetext.;nusagetext.

Further there is the parsing problems of this:

fname1[arguments] or fname2[arguments] usagetext.

Perhaps its better to do this which is easier to parse:

fname1[arguments] usagetext. fname2[arguments] usagetext.

If am misunderstanding anything, please inform me. :-)

Since definitions are at the core of any language, and at the heart of much of western intellectual thought for thousands of years, is there a formal style guide how to define usage correctly and can be easily parsed? Perhaps a definition checker possible using Wolfram's AI work? What makes up a robust, short, and clear usage definition?

Thanks for your help.
POSTED BY: Andrew Meit
Answer
Reply to this discussion
Community posts can be styled and formatted using the Markdown syntax.
Tag limit exceeded
Note: Only the first five people you tag will receive an email notification; the other tagged names will appear as links to their profiles.
Reply Preview
Attachments
Remove
or Discard

Group Abstract Group Abstract