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
80 stars 4 forks source link

Add best practices for toolbox custom documentation #5

Open t-evans23 opened 1 year ago

t-evans23 commented 1 year ago

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

Harald1977 commented 1 year ago

Great idea! Proper doc is always important!

rpurser47 commented 1 year ago

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 commented 1 year ago

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