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 的信息吗？请在评论中提及您的个人偏好。

例子:

%% 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 等...)。将其视为在 Stack Exchange sites 上使用的更简单的 MATLAB 特定版本的 Markdown。格式化帖子。

您没有提到的一个方面是将生成的文档集成到内置帮助查看器中。这是通过创建 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 文档。太糟糕了，他们不与我们的用户分享它:)