生成Matlab HTML文档的Mathworks方法是什么? [英] What is the Mathworks way to generate Matlab HTML documentation?

问题描述

我正在研究共享的Matlab代码，我们希望在本地网络中将生成的文档共享为可搜索的HTML文档.

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:

1. 将转换器写入类似C ++的文件.这是在与Matlab一起使用Doxygen (最后2011年更新)和 mtoc ++ (最新更新时间为2013年).然后由Doxygen解析类似C ++的文件.
2. 使用Python的 sphinxcontrib-matlabdomain 生成HTML文档.
3. 使用 m2html 也是第三方解决方案.
4. 此问答中列出了更多选项:一个，两个和

1. 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.
2. Use Python's sphinxcontrib-matlabdomain to generate a HTML documentation.
3. Use m2html which is also a third-party solution.
4. Further options are listed in this Q&As: One, Two and Three.

Mathworks不支持所有可能性.所有可能性都需要我自己提及，即函数的参数.他们没有从某种意义上分析代码，Doxygen针对Java进行了分析:

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;

我听说过Matlab的 publish()函数，但我从未见过以上述方式使用它.

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

问题:生成Matlab HTML文档的Mathworks方法是什么?可以对代码本身进行分析吗?我可以使用已经提供给Matlab输入解析器的信息吗?请在评论中提及您的个人喜好.

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.

示例:

%% 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);

推荐答案

我认为您已经很好地研究了该主题(如何从MATLAB函数生成HTML文档)，现在由您决定哪种方法最适合您

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.

publish 函数可用于作者文档.您使用专门编写常规M文件精心制作的注释(实际上，该文件可能是没有代码的所有注释)，然后发布文件以获取呈现的HTML(它还支持 Stack Exchange网站上用于此处以格式化帖子.

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.

您没有提到的一个方面是将生成的文档集成到内置的帮助查看器中.这是通过创建 info.xml 和 demos.xml 文件，并在具体方法.您还可以通过使用 Lucene 索引文件来使自定义文档可搜索. www.mathworks.com/help/matlab/ref/builddocsearchdb.html"rel =" nofollow noreferrer> builddocsearchdb 函数(内部为MATLAB自定义文档提供搜索功能).请注意，生成HTML文档的方式并不重要(可以使用publish甚至手动编写HTML文件).

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).

实际上，基于publish的工作流是可扩展的，您可以通过创建自定义渲染方程式 ://www.mathjax.org/"rel =" nofollow noreferrer> MathJax 而不是依赖内置解决方案.另一个示例是发布到MediaWiki标记(维基百科).其他人使用它来撰写博客文章(请参见在MATLAB Central上以这种方式创建的官方博客) ，甚至生成文本文件随后由静态网站生成器处理(例如 Jekyll 和

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).

据我所知，没有可用的公共工具来更深入地检查MATLAB代码并分析函数参数.我能想到的最好的方法是使用 reflection 获取有关函数和类的一些元数据，尽管这种解决方案并不完美.

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似乎正在使用自己的内部系统来编写HTML文档.太可惜他们没有与我们的用户分享:)

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

这篇关于生成Matlab HTML文档的Mathworks方法是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！