Question

Say I’ve written a class in a package, called mypackage.myclass. I’ve written my own HTML documentation for the package and the class, and have included this within the MATLAB help browser as described in the MATLAB documentation.

I can display this HTML documentation by using the help browser to navigate directly to it, but typing doc mypackage.myclass does not display it; instead it displays some HTML documentation that is auto-generated by helpwin (which is a nice feature, but not what I want – the auto-generated documentation is too techy for my users).

How can I force doc to display my documentation, rather than the auto-generated documentation?

Equivalently:

When you run doc docTopic, inside the doc command the Java class com.mathworks.mlservices.MLHelpServices.showReferencePage(docTopic) gets called. If a reference page for docTopic exists, it displays it and returns a success value. If a reference page doesn’t exist, it returns a failure value, which then causes helpwin(docTopic) to get called. Somewhere there must be some catalog that connects values of docTopic with individual reference HTML files. How can I fiddle with that catalog – or can I create one for my package?

MathWorkers and @Yair, please give me enough undocumented rope to hang myself with 🙂

Answer 1

As far as I know this is not possible and not intended by MathWorks. I don’t know of an undocumented way of doing this either. As far as I remember the keywords for doc are hard-coded somewhere.

Depending on your setup you can try the following: Prepare your own doc command that uses web(..., '-helpbrowser') to display HTML pages in MATLAB’s help browser:

function doc(topic)

    my_topics = {
        'foo', 'foo.html'
        'bar', 'bar/help/intro.html'
    };

    for i = 1 : size(my_topics, 1)
        if strcmpi(topic, my_topics{i, 1})      
            web(my_topics{i, 2}, '-helpbrowser');
            return;
        end
    end

    % Fall back to MATLAB's doc. Note that our doc shadows MATLAB's doc.
    docs = which('doc', '-all');
    old_dir = cd();
    c = onCleanup(@() cd(old_dir));
    cd(fileparts(docs{2}));
    doc(topic); 
end

If you put that function in a file doc.m and put the corresponding directory at the beginning of the MATLAB path (see help addpath) then it will be called instead of the built-in doc.

Of course you could use some other place to store your custom doc mapping (a file, for instance) or use some kind of dynamic lookup scheme.

UPDATE: As of MATLAB R2012b, the '-helpbrowser' option of web is undocumented. This is probably related to the GUI changes in that MATLAB version, which also include the help browser. web(..., '-helpbrowser') still works as intended, but that may change in future versions of MATLAB. As far as I know, there is no documented way of opening any HTML page in the help browser in R2012b.