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.