# DocumentationTools in version 13.0: creating documentation from usage

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. and the usage notes can be called when the package is loaded.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. With the pages generated, I can now build the packet however the 2nd and 3rd are not formatted correctly.with the build from the workbench, I did always get proper formatting and splitting of multiple usages for the same function.The same way it looks for the build-in documentation.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
5 Replies
Sort By:
Posted 22 days ago
 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 21 days ago
 Hi Brian,Thanks for the response!If I may, I have two additional questions: 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. 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 13 days ago
 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!