Adding detailed explanations to build documentation pages

[sebdelp]

Hi Thanks for this GitHub, that's very interestign.
May I suggest to add some explanations about building and distributing a "complex" documentation.

1. We can have a "Run livescript" image with a web ink containing the following code
   matlab:dxdzds.file='FILENAME_WITHOUT_EXTENTION';dxdzds.outFile=fullfile(pwd,dxdzds.file); copyfile(which(['user_' dxdzds.file]),[dxdzds.outFile '.mlx']);open(dxdzds.outFile);clear dxdzds;

=> as a result, the example file is copied in the current folder and the user can run it, similarly to Matlab's doc.

2. Overall, there is very few information about folders structure in the documentation about writing a toolbox documentation.

3. Also, the Topics I'd like to be covered are : Explain how to make link between the main documentation pages and the examples : how to add an hyperlink to a specific example from one documentation page and vice versa (adding a link from an example to the main documentation).

4. Overall Matlab documantation about writing documentation is well behind the rest of Matlab documentation. It hasn't be revised for years.
   As we can develop html fils, it is important to understand how the doc is deployed to the user machine during the toolbox install.
   It seems that the actual doc folder structure is not exactly the one we provide in the toolbox folder at the packaging time, making impossible to make link between examples and other pages).

[rpurser47]

Hi Sébastien,

Custom documentation has been a big topic of conversation here recently. We see there being three "levels" of documentation, that authors progress through as their toolbox matures:

1. Examples, hopefully as Live Scripts
2. API documentation, i.e. comment headers at the top of each function
3. Custom documentation, i.e. HTML files distributed with the toolbox

What's your reaction to this? Does that align with your thinking on a toolbox author's journey?

• On number 1 in your question, check out the ability to run your toolbox in MATLAB Online, especially in focus mode.
  https://www.mathworks.com/products/matlab-online/git.html
• On 2, are you asking about how to create a doc link that opens a specific example Live Script? You can do that - here's the documentation for creating links like that: https://www.mathworks.com/help/matlab/matlab_prog/create-hyperlinks-that-run-functions.html
• On 3, I think that's issue Add best practices for toolbox custom documentation #5. Can you add a comment there describing the information you are looking for?
• We're working with the team at MathWorks on item 4.

[sebdelp]

Dear rpurser47

Thansk for the answer.

How do I develop doc? When I start to write a toolbox, I do everything simultaneously:
I comment the code (always, a standard practice) but I also write a doc page for all the objects (main object, parameters and functions), trying to mimic Matlab doc page structure (and I struggle due to the limitation of the live editor). Especially, I try to link the object page with several examples and/or other relevant topic covered by the documentation. When I estimate that most or all the object methods are writen, I wrote an example.
Honestly, linking between doc page works, but linking to examples page barely works.

Overall, I'm globally sad that there is no way (or it is quite difficult) to produce documentation for our toolbox that reaches the Matlab documentation quality. The documentation about how to write a documentation only allows to produce a very basic doc, which is ok for small project but it is very limited. We have now a nice eco-system to share our toolbox, but developping the associated documentation remains very obscure as soon as we would like to mimic some "basic" Matlab doc features.

Last but not least, when writing a toolbox, the associated doc get lost at the end of the toolbox list... I would be very gratefull to have the doc of our toolbox more visible.

Specific answer

1. Opening in live: that's nice but still we do not have an easy way to add the "open in Matlab" buton for the examples that we can provide to the user. I provided a code
2. I was aware of this hyperlink creation, but it would be very nice if some example mlx could be copied in the user current folder when it click on an "open in maltab" button. This could be a feature of the mlx editor to add this button. Then it could be processed when packaging the doc to internally provide this features.

[rpurser47]

Hi @sebdelp -- thanks for your comments on Reddit. This is something that we're working on now, and I'd be interested in talking with you about it in a month or two, when we publish something on github.

One question: We hear about two potential workflows from users:

1. They want to use the comments embedded in their code to automatically generate documentation that gets published near the MATLAB help center, on GitHub pages, a web site, etc.
2. They want to author their documentation in markdown (.md) and "build/publish" their documentation, and potentially run some MATLAB code and have it be part of the published doc.

Does that resonate at all?

[sebdelp]

Hi I'm waiting for new documentation feature since a long time... can't wait anymore. 1. They want to use the comments embedded in their code to automatically generate documentation that gets published near the MATLAB help center, on GitHub pages, a web site, etc. => not really. There are many exterior tools that do that (some support Matlab up to some extent) such as [ https://www.sphinx-doc.org/en/master/ | sphinx ] . For small projects, this can be helpful. If we target "professional" grade product, writing a nice documentation requires more than comments. We need to embed graphics, link pages, etc. 2. They want to author their documentation in markdown (.md) and "build/publish" their documentation, and potentially run some MATLAB code and have it be part of the published doc. Personally, I do not care about the "language" (xml, html, mlx) as long as we are offered a way to produce good quality documentation. So far matlab documentation for custom toolbox is not designed to be a "complex" thing, it is limited to a few pages without to much structure (which is sad because the main value of matlab is its very nice doc). For toolboxes, developing object is very common. There is no dedicated way to produce the corresponding doc. Letting the end user run some code from the doc is a nice idea. Providing him with an editable copy of the example source is a minimum in my opinion. If you need someone for these "user experience" session, to asses an discuss new feature, I'm your man! Sébastien

…

-- Sébastien Delprat Professeur des Universités LAMIH UMR CNRS 8201 Université Polytechnique Hauts-de-France Campus Mont Houy - Bat Malvache n°205 59313 Valenciennes Cedex 9, France Tél : +33 3 27 51 14 88 De: "Rob Purser" ***@***.***> À: "mathworks/toolboxdesign" ***@***.***> Cc: "Sebastien Delprat" ***@***.***>, "Mention" ***@***.***> Envoyé: Mercredi 25 Juin 2025 15:02:51 Objet: Re: [mathworks/toolboxdesign] Adding detailed explanations to build documentation pages (Issue #19) rpurser47 left a comment [ #19 (comment) | (mathworks/toolboxdesign#19) ] Hi [ https://github.com/sebdelp | @sebdelp ] -- thanks for your comments on Reddit. This is something that we're working on now, and I'd be interested in talking with you about it in a month or two, when we publish something on github. One question: We hear about two potential workflows from users: 1. They want to use the comments embedded in their code to automatically generate documentation that gets published near the MATLAB help center, on GitHub pages, a web site, etc. 2. They want to author their documentation in markdown (.md) and "build/publish" their documentation, and potentially run some MATLAB code and have it be part of the published doc. Does that resonate at all? — Reply to this email directly, [ #19 (comment) | view it on GitHub ] , or [ https://github.com/notifications/unsubscribe-auth/AK4MW75ZKHV7ARCBFJDHYRD3FKMXXAVCNFSM6AAAAACADHV7D6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTAMBUGY4TGMJSGY | unsubscribe ] . You are receiving this because you were mentioned. Message ID: < ***@***.*** >

[rpurser47]

If you need someone for these "user experience" session, to asses an discuss new feature, I'm your man!

I hope to be in touch soon!
-Rob