matlab - Mathworks 生成 Matlab HTML 文档的方法是什么？

Question

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

我知道以下生成文档的方法:

1. 编写一个类似于 C++ 文件的转换器。这是在 Using Doxygen with Matlab 中完成的(最后更新于 2011 年)和 mtoc++ (最后更新于 2013 年)。然后，Doxygen 会解析类似 C++ 的文件。
2. 使用Python的sphinxcontrib-matlabdomain生成 HTML 文档。
3. 使用m2html这也是第三方解决方案。
4. 此问答中列出了更多选项:One , Two和 Three .

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

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

我听说过Matlab的publish()函数，但我从未见过它在上述意义上使用过。

问题:Mathworks 生成 Matlab HTML 文档的方式是什么。代码本身可以分析吗？我可以使用提供给 Matlab 输入解析器的信息吗？请在评论中提及您的个人偏好。

示例:

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

Answer 1

我认为您已经很好地研究了这个主题(如何从 MATLAB 函数生成 HTML 文档)，现在您可以选择最适合您的方法。

publish函数可用于author documentation 。您可以使用 specially crafted comments 编写常规 M 文件(事实上​​，该文件可以是没有代码的所有注释)，然后您发布该文件以获得渲染的 HTML(它还支持 other targets 例如 PDF、DOC、LaTeX 等...)。将其视为更简单的 MATLAB 特定版本的 Markdown，它在 Stack Exchange sites 上使用。设置帖子格式。

您没有提到的一个方面是将生成的文档集成到内置的帮助查看器中。这是通过创建 info.xml 来完成的和 demos.xml文件，并以特定方式组织文档。您还可以通过构建 Lucene 使您的自定义文档可搜索。使用 builddocsearchdb 索引文件函数(在内部支持 MATLAB 自定义文档中的搜索功能)。请注意，您如何生成 HTML 文档并不重要(您可以使用 publish 甚至手动编写 HTML 文件)。

事实上，基于 publish 的工作流程是可扩展的，您可以通过创建自定义 XSL 以有趣的方式使用它。用于转换和呈现已解析注释的模板文件。例如，我见过它曾经 render equations使用MathJax而不是依赖内置解决方案。另一个例子是 publishing to MediaWiki markup ( Wikipedia 使用的格式)。其他人用它来撰写博客文章(请参阅 MATLAB Central 上以这种方式创建的 official blogs)，甚至 generate text files稍后由静态站点生成器处理(如 Jekyll 和 Octopress 框架)。

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

MathWorks 似乎正在使用他们自己的内部系统来编写 HTML 文档。太糟糕了，他们不与我们用户分享:)