README

基于多个供应商安装的 schemas，生成 Fluid ViewHelper 文档的静态站点。

核心功能

在公共文件夹中生成 HTML 网站（通过 Fluid 模板引擎），为每个 schema 提供服务，按供应商和包名分开，并包含导航。HTML 导出器默认可以渲染 Markdown。
生成包含导航 JSON 结构的 URL 的 JSON 数据，类似于 GitHub 的 API。
作为公共文件下载 XSD 文件。
生成完全可预测的 URL，可以根据类名等外部构建。
可以扩展额外的发布方法。

如何使用

克隆存储库或基于 namelesscoder/fluid-documentation-generator 开始一个新项目。
将您的 schema 文件放在根路径的 schemas 目录中。例如，具有 composer 名称 myvendor/my-packge 的包的版本 1.2.3 的 schema 必须复制到 schemas/myvendor/my-package/1.2.3/schema.xsd。
运行 ./bin/generate-fluid-documentation 或 composer generate
启动 Web 服务器或将虚拟主机指向 public 目录，或者简单地从公共文件夹中打开 index.html 文件，在本地浏览文档。

每个供应商、包和版本目录也可以配合一个包含数据的 metadata.json 文件，这些数据是 XSD schema 文件无法包含的 - 例如，包使用的 PHP 命名空间和首选命名空间别名。请参阅以下部分，以获取有关这些元数据清单的详细信息。

命令支持恰好三个参数。如果您希望指定第二个参数，则必须先指定第一个，依此类推。然而，参数可以是空的，以使默认值生效。

./bin/generate-fluid-documentation "`pwd`/public/" "http://localhost/" 1
# Or, if you just want defaults but need to specify the last argument:
./bin/generate-fluid-documentation "" "" 1

解释命令参数

文件发布的公共目录 - 默认情况下，这是应用程序根文件夹中的 public/ 目录。更改此目录显然会更改所有公共文件创建的位置。
生成的文件将可访问的公共 URL。如果您想在 Web 服务器上提供服务，请提供此 URL。该 URL 用作绝对链接的前缀，并为 JSON 文件（所有这些 URL 都是绝对 URL）和在不同页面上呈现的“资源”链接生成特定于绝对链接。JSON 中的 URL 当然是绝对 URL，因此您可以按程序遍历它们。“资源”链接始终是绝对 URL，以便如果您在本地查看文件，单击任何链接或复制它们给用户，都会给您绝对 URL。
一个布尔值（1/0），指定是否执行所有生成文件的强制更新。如果为 false，则不会重新生成已存在的任何文件。如果您将其添加到 cron 并定期从集合中生成，则不需要连续重写一切，这很有用。当然，尚未存在的文件将被创建。

元数据文件

可以在 schemas 文件夹的不同级别放置一组有限的元数据文件

在 schemas 目录中，可以放置一个 README.md 文件，它将被渲染为根索引 HTML 页面。
在供应商、包和版本目录中，可以放置一个README.md文件，该文件将显示在相应的概览页上。但是，由于第三方的用户将管理这些文件，因此所有HTML都将被删除。支持Markdown格式，但链接标签会被移除。
同样，在所有三个目录中，可以放置一个metadata.json文件。类似于.htaccess文件，这些文件将按照更具体文件变量覆盖更通用变量的方式进行合并（在包中定义的变量会覆盖供应商元数据文件中定义的同名变量）。

供应商的metadata.json可能包含以下内容：

{
  "outlets": {
    "github": true,
    "packagist": true
  }
}

包或特定版本的包的metadata.json可能包含以下内容：

{
  "namespace": {
    "alias": "v",
    "php": "\\FluidTYPO3\\Vhs\\ViewHelpers\\"
  },
  "outlets": {
    "github": true,
    "packagist": true,
    "ter": "vhs"
  }
}

（注意，ter输出值必须包含TYPO3扩展密钥）

所有设置都是可选的。命名空间信息在渲染模式和ViewHelper信息时使用，启用的输出将导致链接到这些输出（通过惯例使用供应商和包名称生成）。

在较高级别定义的内容将继承到较低级别。例如，包继承自供应商元数据，版本元数据继承自包和供应商。

支持的命令行参数

命令行工具恰好需要三个参数。参数没有命名，并且必须按顺序传递。

应用程序数据文件夹的绝对或相对路径。
应用程序公共文件夹的绝对或相对路径。
公共文件夹的绝对URL - 通常为http://或https://，但也支持file://目录路径。

绝对URL仅在生成JSON API资源时才有用。HTML界面可以在不提供公共URL的情况下使用，并且可以通过HTTP或通过在浏览器中打开HTML文件来工作。然而，请注意，XSD和JSON模式资源链接只能通过...

如果绝对URL不是file:// URL并且可以访问。
或者HTML界面作为本地文件加载，没有提供绝对URL或提供了file:// URL。

换句话说，远程文件的链接在任何协议上都能工作 - 而本地文件的链接仅在工作在本地协议上。但是HTML文件在两种模式下都能工作。

继续阅读以下内容以了解更多信息。

如何作为远程API消费

可以通过对提供生成文档的公共文件夹的主机进行简单的GET请求，获取有关供应商、包、版本、模式和单个ViewHelper的信息。

该应用程序将生成作为图形数据的JSON资源，这意味着无论您请求哪个JSON资源，它都将始终包含“主要”资源以及其他相关资源的摘要版本。

每个图形数据实体都配备了一组URL，这些URL将提供有关该实体的更多信息。这意味着您可以从特定模式中的ViewHelper开始迭代，并获取访问HTML渲染所需的所有URL，为相关资源请求详细的JSON图形数据，等等。

您可以从您指定的公共文件夹中的index.json文件开始导航JSON图形数据。与HTML输出相反，JSON图形数据将始终使用绝对URL链接（作为命令行工具的参数提供）。如果没有提供自定义公共URL前缀，则应用程序将生成作为file://链接的JSON链接，如果HTML不是通过file:// URL提供服务，则这些链接将破坏从ViewHelper参考页面到JSON模式的链接。如果输出将通过HTTP提供服务，请确保您提供指向公共文件夹的绝对URL前缀。

HTML界面还会显示JSON API链接，如果使用了JSON导出器。

如何自定义资源生成

自定义CSS（或添加JS到其中）相对直接。公共文件夹中包含一个名为_assets的文件夹，默认包含一个styles.css文件。该文件由Default布局包含，该布局由应用根目录中的resources文件夹渲染。所有模板都使用Fluid进行渲染。

如果您希望扩展默认的模板集合或更改使用的导出器（例如，防止导出JSON模式）您需要从bin/generate-fluid-documentation脚本中复制逻辑。不包括类加载器和类导入，该脚本如下

$dataDirectory = $argv[1] ?? $pwd . DIRECTORY_SEPARATOR . 'data' . DIRECTORY_SEPARATOR;
$publicDirectory = $argv[2] ?? $pwd . DIRECTORY_SEPARATOR . 'public' . DIRECTORY_SEPARATOR;
$publicUrlPrefix = rtrim($argv[3] ?? 'file://' . $publicDirectory, '/') . '/';

$resolver = DataFileResolver::getInstance($pwd);
$exporters = [
    new XsdExporter($publicUrlPrefix),
    new JsonExporter($publicUrlPrefix),
    new HtmlExporter($publicUrlPrefix),
];
$generator = new SchemaDocumentationGenerator($exporters);

echo 'Generating static files for:' . PHP_EOL;
foreach ($resolver->resolveInstalledVendors() as $vendor) {
    $generator->generateFilesForVendor($vendor);
    foreach ($vendor->getPackages() as $package) {
        $generator->generateFilesForPackage($package);
        echo '> ' . $vendor->getVendorName() . '/' . $package->getPackageName() . ': ';
        foreach ($package->getVersions() as $version) {
            echo $version->getVersion() . ' ';
            $generator->generateFilesForSchema(new Schema($version));
        }
        echo PHP_EOL;
    }
}

它包含三个主要部分

解析数据目录和公共目录路径，以及提供的公共URL。默认值来自工作目录。
导出器的分配 - 实现共享接口的特殊类，每个类提供一种资源导出类型；复制XSD文件、生成JSON API文件和生成HTML。请注意，JsonExporter和XsdExporter都需要一个绝对公共URL作为参数（有关此公共URL，请参阅上方）；HtmlExporter应该也有公共URL，尽管在不导出JSON模式且不希望导出的JSON中有HTML链接时，这不是必需的。
一个三维循环，遍历所有已安装的供应商、所有已安装的包、每个包的所有版本以及该版本包模式中记录的每个ViewHelper。

只要复制这三个部分，这个逻辑就可以在任何地方调用 - 当然，用户反馈可以从echo()更改到您喜欢的任何方法。

命令行实用程序是一个“启用已发货导出器、处理所有内容的最低限度的”样式的脚本，它会生成所有内容。您还可以生成单个版本的原子更新。

关于服务单个包/版本等的说明。

公共文件夹使用完整的$vendor/$package/$version结构生成，这意味着如果通过HTTP提供服务并操作文档根设置，则可以提供

特定供应商（或您自己的）的所有包
特定供应商（或您自己的）的特定包
特定版本的包

每个文件夹维度都配有一个index.html文件，以便用作起点。在服务公共文件夹的子集时，有一个小不便之处：将用户带到您不提供的服务类型概览的链接将最终停留在您提供的最高级别。例如，将您带到供应商概览（正常公共根）的链接在您只提供服务包但不是特定版本的包时，将指向版本列表。

namelesscoder / fluid-documentation-generator

维护者

详情