Hi, I have some questions about auto-generating documentation for a custom module. I have a Matlab function to create my custom module which is in this format:
function sys = matlab_function_name_module(NAME)
% Some helpful comments and documentation
sys = awe_subsystem('ModuleNameString', 'Description of my module');
sys.name = NAME;
% More code to do useful things
The name of the file containing this function matches the function name. In a different script, I use these commands for generating the documentation:
sys = matlab_function_name_module('name');
awe_generate_doc(sys, 'name_of_documentation_folder');
This works fine, and generates some HTML documentation. But I have a few issues/questions:
- When I call from the Matlab command line `awe_help matlab_function_name_module`, I get an error saying "Error using awe_help, No help documentation exists for module". According to Section 6.1 "awe_help" of the Custom Module Developers' guide (page 108 in my version), I thought that calling this command should generate documentation on the fly if it doesn't already exist in the correct location. What is going wrong here, that an error is being thrown, instead of the correct documentation being generated? (I also tried using the command `awe_help ModuleNameString`, which to my surprise didn't throw an error, but also didn't load up any HTML documentation in my browser)
- When I drag this custom module into an AWE designer window from the sidebar and right-click on the module, the option for "Help" is greyed out and inaccessible. What do I have to do to be able to access "Help" by right-clicking on the module in Designer? (I notice other 3rd party modules not developed by us do not seem to have the "Help" option greyed out)
- It says in Section 6.3 "Selecting the Documentation Format" of the module developers guide that using the command `AWE_INFO.docControl.format='doc';` should generate documentation in Word format, but for me, after calling `global AWE_INFO`; AWE_INFO.docControl.format='doc'; awe_generate_doc(...);`, the documentation was still in HTML format. How do I get documentation in Word format?
- In the generated HTML documentation, under "Type Definition", I only have the text "-- Not Shown --". What do I need to do to get a proper type definition shown here?
Thank you,
Jake
3:49pm
Hi Jake,
Unfortunately, while the Module Developers Guide is still quite useful, it is also somewhat dated. There is an up to date Module Writing Tutorial that can be found here: https://youtu.be/thxyK9pX8fs?t=2666. I've time stamped the section on generating documentation, but the whole video itself is worth watching. This should help, but let me know if it doesn't work or you have more questions.
Thanks,
Kevin
6:35am
Hi Kevin, thank you for your reply. In the video, at the t=2666 timestamp (44:30), the narrator just says "Call the Matlab make function", and enters the command `make_tutorial_module_pack(1)`, but he doesn't explain where this function comes from. I tried entering this command in my Matlab command prompt, and got the error "Unrecognized function or variable 'make_tutorial_module_pack'. ". Where does this function come from?
Also, I think I mentioned in an earlier forum post it would be useful to have auto-generated online HTML documentation for AWE, including the Matlab API. I think the fact that a PDF document can easily become outdated and need to be updated and re-downloaded is another point in favour of this.
Thanks,
Jake
11:13am
Hi Jake,
There is a "make_*" Matlab script that's mentioned earlier in the video, and also the pages 15-20 of the Module Developer's Guide, which I think you were following. The script will live in the Matlab folder of your Custom Module's parent directory. I don't want to create any double work for you, but it really helps to watch the video in it's entirety from beginning to end since it is the most updated documentation on Custom Modules. I'll me email you a 'make_' script shortly.
Also, yes I did see you mention about the HTML documentation before. It's a good idea, thank you. I logged a ticket for this update to our development team when you suggested the first time.
Thanks,
Kevin