Matlab – the Mathworks way to generate Matlab HTML documentation

documentation-generationdoxygenMATLABpython-sphinx

I am working on shared Matlab code and we would like to share a generated documentation as searchable HTML documents within our local network.

I know of the following methods to generate a documentation:

Write a converter to C++-like files. This is done in in Using Doxygen with Matlab (Last updated 2011) and mtoc++ (last updated 2013). The C++-like files are then parsed by Doxygen.
Use Python's sphinxcontrib-matlabdomain to generate a HTML documentation.
Use m2html which is also a third-party solution.
Further options are listed in this Q&As: One, Two and Three.

All possibilities are not supported by Mathworks. All possibilities need me to mention i.e. the parameters of a function myself. They do not analyze the code in the sense, Doxygen does it for i.e. Java:

//! an object representation of the advertisement package sent by the beacon
private AdvertisementPackage advertisementPackage;

I heard of Matlab's publish() function, but I did never see it used in the aforementioned sense.

Question: What is the Mathworks way to generate Matlab HTML documentation. Can the code itself be analyzed? Can I use the information provided to the Matlab Input Parser already? Please mention your personal preference in comments.

Example:

%% Input parser
p = inputParser;
addRequired(p, 'x', @isnumeric);

validationFcn = @(x) (isnumeric(x) && isscalar(x));
addRequired(p, 'fftSize', validationFcn);
addRequired(p, 'fftShift', validationFcn);

validationFcn = @(x) (isa(x, 'function_handle'));
addRequired(p, 'analysisWindowHandle', validationFcn);

parse(p, x, fftSize, fftShift, analysisWindowHandle);

Best Answer

I think you've researched this topic well (how to generate HTML documentation from MATLAB functions), now it's up to you to choose which method works best for you.

The publish function could be used to author documentation. You write regular M-files with specially crafted comments (in fact the file could be all comments with no code), then you publish the file to obtain rendered HTML (it also supports other targets such as PDF, DOC, LaTeX, etc...). Think of it as a simpler MATLAB-specific version of Markdown which used here on Stack Exchange sites to format posts.

One aspect you didn't mention is integrating the generated documentation into the builtin Help viewer. This is done by creating info.xml and demos.xml files, and organizing the documentation in a specific way. You could also make your custom docs searchable by building Lucene index files using builddocsearchdb function (which internally powers the search functionality in MATLAB custom docs). Note that it doesn't matter how you generated the HTML docs (you could have used publish or even manually written HTML files).

In fact the publish-based workflow is extendable, and you could use it in interesting ways by creating custom XSL template files to transform and render the parsed comments. For example I've seen it used to render equations using MathJax instead of relying on the built-in solution. Another example is publishing to MediaWiki markup (format used by Wikipedia). Other people use it to write blog posts (see the official blogs on the MATLAB Central which are creating this way), or even generate text files later processed by static site generators (like Jekyll and Octopress frameworks).

As far as I know, there are no public tools available that inspect MATLAB code on a deeper level and analyze function parameters. Best I could come up with is using reflection to obtain some metadata about functions and classes, although that solution is not perfect...

MathWorks seems to be using their own internal system to author HTML documentation. Too bad they don't share it with us users :)

On auto-generating C++ documentation:

After reading up on how to use sphinx at all, you should have a look into breathe:

Breathe provides a bridge between the Sphinx and Doxygen documentation systems.

It is an easy way to include Doxygen information in a set of documentation generated by Sphinx. The aim is to produce an autodoc like support for people who enjoy using Sphinx but work with languages other than Python. The system relies on the Doxygen’s xml output.

So additionally, you'll need to follow Doxygen commenting style and even setup an doxygen project. But I tried that and it works really well after the initial setup took place. Here is an excerpt of our CMakeLists.txt which might give you an idea on how sphinx and doxygen work together:

macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
    add_custom_target(${TARGET_NAME}
    COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
        WORKING_DIRECTORY docs
        DEPENDS doxygen
        COMMENT ${COMMENT_STR}
    )

endmacro(add_sphinx_target)

add_custom_target(doxygen
    COMMAND doxygen docs/doxygen.conf
    COMMENT "Build doxygen xml files used by sphinx/breathe."
)

add_sphinx_target(docs-html
    html
    "Build html documentation"
)

So after initial setup, essentially it boils down to:

build doxygen documentation with doxygen path/to/config
cd into the directory where the sphinx configuration is.
build sphinx documentation with sphinx-build . path/to/output

On the c++ domain:

Sphinx is a „little bit“ more than a system to auto-generate documentation. I would suggest you have a look at the examples (and consider that the sphinx website itself is written in sphinx reST code). Especially click the Show Source link on many sphinx-generated pages.

So if you cannot generate documentation automatically for a project, you have to do it yourself. Basically sphinx is a reST to whatever (LaTeX, HTML, …) compiler. So you can write arbitrary text, but the advantage is that it has a lot of commands for documenting source code of different languages. Each language gets its own domain (prefix or namespace) to separate the namespaces of the different languages. So for example I can document a python function using:

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
    Does something nasty with timers in repetition

(source)

I can do the same using the cpp domain:

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

(source)

So if you want to document your c++ project without doxygen+breathe but with sphinx, you'll have to write the restructured text files yourself. This also means that you split the documentation from your source code, which can be undesirable.

I hope that clears things up a bit. For further reading I strongly suggest that you have a good read on the sphinx tutorial and documentation until you understood what it actually does.

C++ – How to know the size of a frame or image

Try the following code :) The key point is the usage of cvGetSize function and CvSize structure.

#include "cv.h"
#include "highgui.h"
#include "iostream"

using namespace std;
int main( int argc, char* argv ) {

CvCapture *capture = NULL;
capture = cvCaptureFromAVI("C:\\walking\\lady walking.avi");
if(!capture){
    return -1;
}

IplImage* color_frame = NULL;
IplImage* gray_frame = NULL ;

int thresh_frame = 17;

int frameCount=0;//Counts every 5 frames
cvNamedWindow( "contours", CV_WINDOW_AUTOSIZE );

while(1) {
    color_frame = cvQueryFrame( capture );//Grabs the frame from a file
    if( !color_frame ) break;
    gray_frame = cvCreateImage(cvSize(color_frame->width, color_frame->height), color_frame->depth, 1);
    if( !color_frame ) break;// If the frame does not exist, quit the loop

    frameCount++;
    if(frameCount==5)
    {
        cvCvtColor(color_frame, gray_frame, CV_BGR2GRAY);
        cvThreshold(gray_frame, gray_frame, thresh_frame, 255, CV_THRESH_TOZERO_INV);

        CvSize dim = cvGetSize(gray_frame);

        cout <<" dimensions:: height:" <<  dim.height<<" width:"<< dim.width<< endl;

        cvShowImage("contours", gray_frame);
        frameCount=0;
    }
    char c = cvWaitKey(33);
    if( c == 27 ) break;
}

cvReleaseImage(&color_frame);
cvReleaseImage(&gray_frame);
cvReleaseCapture( &capture );
cvDestroyWindow( "contours" );

return 0;
}

Best Answer

Related Solutions

C++ – Using Sphinx-apidoc to generate documentation from C++ code

On auto-generating C++ documentation:

On the c++ domain:

C++ – How to know the size of a frame or image

Related Topic