显示自定义示例

如何显示示例

要在 MathWorks^® 文档中显示视频、已发布的程序脚本等示例，或者其他演示您的程序用法的文件，请执行下列步骤：

创建您的示例文件。要从脚本或函数创建示例，您可以使用以下两种方法之一将文件转换为 MATLAB^® 中的格式化 HTML 文件：
- 创建实时脚本 (*.mlx) 并将其导出为 HTML。有关详细信息，请参阅共享和导出实时脚本和函数的方法。
- 创建脚本 (*.m) 并将其发布为 HTML。有关详细信息，请参阅发布和共享 MATLAB 代码。
将工具箱的所有示例文件和任何支持文件（如 PNG 和 CSS 文件）存储在包含 demos.xml 文件的文件夹（或该文件夹的子文件夹）中。此文件夹必须：
- 位于 MATLAB 搜索路径中
- 位于 matlabroot 文件夹之外
- 位于任何已安装的硬件支持包帮助文件夹之外

创建一个 demos.xml 文件来描述您的示例的名称、类型以及显示信息。将文件放在包含您的 info.xml 文件的文件夹（或该文件夹的子文件夹）中。有关创建 info.xml 文件的详细信息，请参阅显示自定义文档。

例如，假设您有一个名为 My Sample 的工具箱，其中包含一个您发布为 HTML 的名为 my_example 的脚本。此 demos.xml 文件允许您显示 my_example：

<?xml version="1.0" encoding="utf-8"?>
<demos>
    <name>My Sample</name>
    <type>toolbox</type>
    <icon>HelpIcon.DEMOS</icon>
    <description>This text appears on the main page for your examples.</description>
    <website><a href="https://www.mathworks.com">Link to your Web site</a></website>

    <demosection>
        <label>First Section</label>
        <demoitem>
            <label>My Example Title</label>
            <type>M-file</type>
            <source>my_example</source>
        </demoitem>
    </demosection>

</demos>

查看您的示例。
在您的系统 Web 浏览器中，导航到 MathWorks 文档主页。在主页左侧的补充软件下，点击对应您示例的链接。
如果您的示例没有显示在补充软件下，demos.xml 文件可能包含无效构造。

demos.xml 文件的元素

在 demos.xml 文件中，您可以在 <demos> 标记中包含一般信息，使用 <demoitem> 标记定义各个示例，也可以选择使用 <demosection> 标记定义类别。

使用 `<demos>` 标记包含一般信息

在 demos.xml 文件中，根标记是 <demos>。该标记包括可确定您的示例的主页内容的元素。

XML 标记	注释
`<name>`	工具箱或示例集合的名称。
`<type>`	可能的值包括 `matlab`、`simulink`、`toolbox` 或 `blockset`。
`<icon>`	在 MATLAB R2015a 和更新版本中已忽略。在之前的版本中，此图标是对应您示例的图标。在那些版本中，您可以使用标准图标 `HelpIcon.DEMOS`。您也可以通过指定相对于 `demos.xml` 文件位置的路径提供自定义图标。
`<description>`	显示在您的示例的主页上的说明。从 R2021a 开始，`demos.xml` 文件的说明中不支持字符数据。如果您的 `demos.xml` 文件的说明中包含字符数据，如 `<`、`>`、`'`、`"` 和 `&`，则说明在文档中不会正确显示。要用非字符数据自动替换现有字符数据，请使用 `patchdemoxmlfile` 函数。
`<website>`	（可选）链接到网站。例如，MathWorks 示例包括一个指向位于 `https://www.mathworks.com` 的产品页的链接。

使用 `<demoitem>` 标记定义示例

XML 标记	注释
`<label>`	定义要显示在浏览器中的标题。
`<type>`	可能的值包括 `M-file`、`model`、`M-GUI`、`video` 或 `other`。通常，如果您使用发布函数发布了您的示例，则相应的 `<type>` 为 `M-file`。
`<source>`	如果 `<type>` 为 `M-file`、`model`、`M-GUI`，则 `<source>` 是关联的 `.m` 文件或模型文件的名称且不带扩展名。否则，请不要包括 `<source>` 元素，而应包括 `<callback>` 元素。
`<file>`	当您要显示描述示例的 HTML 文件时，仅对包含除 `M-file` 之外的 `<type>` 值的示例使用此元素。指定相对于 `demos.xml` 位置的路径。
`<callback>`	仅对 `<type>` 值为 `video` 或 `other` 的示例使用此元素，以指定可执行文件或 MATLAB 命令执行此示例。
`<dependency>`	（可选）指定运行该示例所需其他产品，例如另一个工具箱。文本必须与位于搜索路径上或当前文件夹中的 `info.xml` 文件中指定的产品名匹配。

使用 `<demosection>` 标记定义类别

或者，通过包含每个类别的 <demosection> 来定义您的示例的类别。如果您包含任意类别，则所有示例都必须在类别中。

每个 <demosection> 示例都包含一个 <label>，后者提供类别名称以及相关联的 <demoitem> 元素。

另请参阅

patchdemoxmlfile

主题

显示自定义文档