search

mathworks / toolboxdesign

Best practices for creating high-quality and user-friendly MATLAB toolboxes, including recommendations for file organization, testing, and releasing the toolbox.
Creative Commons Attribution 4.0 International
87 stars 4 forks source link

Recommended placement of gettingStarted.mlx conflicts with MATLAB documentation #18

Closed eddins closed 2 months ago

eddins commented 7 months ago

The recommended location for gettingStarted.mlx is "at the top level of the toolbox folder." This recommendation conflicts with the MATLAB documentation page, "Create and Share Toolboxes," which says:

"For the Package a Toolbox tool to recognize a Getting Started Guide, include the guide as a live script named GettingStarted.mlx in a doc subfolder within your toolbox folder."

There is also a capitalization discrepancy (gettingStarted.mlx vs GettingStarted.mlx).

eddins commented 7 months ago

I see in the documentation for ToolboxOptions that there is a scriptable way to tell the toolbox packager where to find the getting started file. That lessens the importance of this issue, in my mind, but I think it would still be worthwhile to reconcile the two recommendations.

rpurser47 commented 2 months ago

Hi Steve,

Hope you're doing well. Yes -- there is a conflict between our recommendations and what is currently documented. We've worked with the various teams at MathWorks who are associated with this to make sure that future versions of the documentation system, toolbox packaging, and File Exchange align on this best practice. Our position is that the gettingStarted.mlx is so important that it belongs prominently at the top of a toolbox, rather than down in the doc directory, even though it doesn't match the assumptions that the tooling makes about it.

Like you mention, the ToolboxGettingStartedGuide property on the matlab.addons.toolbox.ToolboxOptions object can be set to point to the GettingStarted.mlx. As an example, we do this in the Arithmetic Toolbox example in the buildfile.m: https://github.com/mathworks/arithmetic/blob/41a80d9c36c86cba2dca20c0d278dc0fa3a17090/buildfile.m#L31

-Rob