Add best practices for toolbox custom documentation

[t-evans23]

Add description and example of best practices for custom documentation for toolbox folders and files.

[Harald1977]

Great idea! Proper doc is always important!

[rpurser47]

Capturing the comment from Reddit:

This one was right on the edge of making it into v1 of the best practice. Here's my advice:

You can create custom documentation for functions in your toolbox. Place your shipping documentation in a doc folder under the toolbox folder. Custom documentation requires the following files:

1. HTML help files

2. info.xml

3. helptoc.xml

You can use the publish command to create documentation HTML help files.

When we add custom documentation to our example toolbox:

arithmetic/ 
: 
├───toolbox/ 
│   │   gettingStarted.mlx 
│   │   info.xml 
│   ├───doc/ 
│   │      helptoc.xml
│   │      coolDoc.mlx 
│   ├──────html/ 
│   │         coolDoc.html

Please understand that this was draft advice, and is subject to change in the future.

[rpurser47]

This is something that we'll add in a future revision.

[sebdelp]

R2024b break what was barely working....
Just a simple example, in a doc page written as an mlx file, the table of content links are broken once the doc is generated.

It was already be difficult to provide a nice "example experience" to the user especially having the possibility to run some code in the user editor. But it was still possible by executing copy command with "matlab:" pragma in an html link. Now this does not work because the doc is now displayed by the system browser.
I'm again lost how to provide a way for the user to download a custom toolbox example from its html page... any idea? Is there a way that we integrate a "copy command" button in our documentation?

I really urge the Matlab dev team to rework the way user can provide high quality documentation to their users. It is really sad that this has not been reworked for years. Matlab main strength its is high quality doc. This should be available for custom toolbox.

Now the doc is pure html. Most/many of us will follow the advices and use mlx files to generate our doc.
The official Matlab doc about example is really confusing. See here: there is no reference to mlx file. So how do you deal with mlx example files?
The whole field descriptions of the is outdated:

• : what about mlx file
• : should we use that with mlx files?
• : does it still allow to run Matlab command ?

It is absolutely not clear to me why we have to declare example in a dedicated xml file as there is absolutely no benefits to do this:

1. our custom toolbox examples are not integrated with Matlab example management: they are not displayed in the same way as regular examples and they are not found wind openExample.
2. when browsing to our custom examples page, the menu of our custom toolbox help disappears. To get back to the custom toolbox doc user have to click on a meaning less "supplementary software" link. Note that on the same menu there are 2 links with the same "display" ("supplementary software"). The first one (on top of the menu) links to the real supplementary software index (list of all the custom toolboxes). The second one is a link to the current toolbox main help page
3. User cannot download example files. It is up to the developper to find a way to bypass all the limitations. Mathworks does not provide an official way to do it.

So far the user experience is much better by displaying the example page as a "normal" subsection of the main doc.
This is frustrating as much more could be done by exploiting the provided xml files

Please Mahtworks, do something with the custom toolbox help.

[rpurser47]

We have not forgotten this -- my thinking is that we'll offer a best practice in the next couple of months. Apologies for the delay.