README

Berlioz Doc Parser 是一个用于解析文档并允许在网站等地方集成的 PHP 库。

安装

Composer

您可以使用 Composer 安装 Berlioz Doc Parser，这是推荐安装方式。

$ composer require berlioz/doc-parser

依赖关系

• PHP ^8.0
• PHP 库
  • mbstring
• 包
  • berlioz/html-selector
  • berlioz/http-message
  • league/flysystem

为了解析文件，您需要额外的包

• 对于 Markdown 文件： league/commonmark
• 对于 reStructuredText 文件： gregwar/rst

使用方法

库使用 league/flysystem 库来操作文件。此库允许使用一些适配器，如 本地文件、GitLab、Google 等，这对文档源非常有用。

文档生成

您需要定义文档的解析器，例如： Berlioz\DocParser\Parser\Markdown。

use Berlioz\DocParser\DocGenerator;
use Berlioz\DocParser\Parser\Markdown;
use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;

$version = '1.0';

$docGenerator = new DocGenerator();
$docGenerator->addParser(new Markdown());
$documentation =
    $docGenerator->handle(
        $version,
        new Filesystem(new LocalFilesystemAdapter('/path-of-project/doc'))
    );

文档文件

您可以轻松访问文档文件

/** @var \Berlioz\DocParser\Doc\Documentation $documentation */
$files = $documentation->getFiles();

并且可以通过类型筛选文件

use Berlioz\DocParser\Doc\File\FileInterface;
use Berlioz\DocParser\Doc\File\Page;

/** @var \Berlioz\DocParser\Doc\Documentation $documentation */
$pages = $documentation->getFiles(fn(FileInterface $file) => $file instanceof Page);

存在两种文件类型

• Berlioz\DocParser\Doc\File\Page：包含解析内容的页面
• Berlioz\DocParser\Doc\File\RawFile：原始文件，如图片

文档处理

当文档生成后，您可以使用 Documentation::handle() 方法来获取页面和文件。

use Berlioz\DocParser\Doc\Documentation;
use Berlioz\DocParser\Doc\File\Page;

/** @var Documentation $documentation */
$file = $documentation->handle('path/of/my/page');

if (null === $file) {
   // Show not found error
}

// Raw file?
if (!$file instanceof Page) {
    // Return \Psr\Http\Message\ResponseInterface object
    return $file->response();
}

// Show HTML content of my page
echo $file->getContents();

处理

实现了一种处理概念，用于在生成后操作文件。

一些处理默认启用

• Berlioz\DocParser\Treatment\DocSummaryTreatment：生成文档摘要
• Berlioz\DocParser\Treatment\PageSummaryTreatment：生成页面摘要
• Berlioz\DocParser\Treatment\PathTreatment：解析所有链接以转换为相对链接
• Berlioz\DocParser\Treatment\TitleTreatment：提取页面标题并将其设置到 Page 对象中

可选的处理可用

• Berlioz\DocParser\Treatment\BootstrapTreatment：为 HTML 元素添加 CSS 类以美化 Bootstrap 框架

您也可以创建自己的处理类并将其添加到生成器中

use Berlioz\DocParser\DocGenerator;
use Berlioz\DocParser\Treatment\BootstrapTreatment;

/** @var DocGenerator $docGenerator */
$docGenerator->addTreatment(new BootstrapTreatment($docGenerator));

格式

Markdown

用于文档索引的特定标签

```index
title: Title of page
slug: Slug name (replace only the filename, not path)
breadcrumb: Category; Sub category; My page
summary-order: 1
summary-visible: true
```

reStructuredText

用于文档索引的特定指令

...index:
    :title: Title of page
    :slug: Slug name (replace only the filename, not path)
    :breadcrumb: Category; Sub category; My page
    :summary-order: 1
    :summary-visible: true

可用的索引选项

• title：替换页面标题，标题处理不替换此标题
• slug：替换页面文件名，而不是完整路径，它是值的 URL 编码表示
• breadcrumb：页面在文档摘要中的面包屑，如果不存在，则页面不会在摘要中
• summary-order：摘要部分中的顺序
• summary-visible：默认为 true，但您可以将页面定义为不在摘要中可见

您可以为您的处理定义自己的选项，例如，使用 Page::getMeta(...) 方法。

摘要

文档摘要

文档摘要引用所有带面包屑的页面。它是一系列 Berlioz\DocParser\Doc\Summary\Entry 对象的层次结构。

您可以使用 Entry::getPath() 方法获取条目的路径，它是文档根目录的绝对路径。

页面摘要

页面摘要引用页面内容中的所有标题。它是一系列 Berlioz\DocParser\Doc\Summary\Entry 对象的层次结构。

条目没有给定路径，但有 id Entry::getId()，它与相应的标题相关联。

解析器

默认情况下提供两种解析器

• Berlioz\DocParser\Parser\Markdown：解析Markdown文件，使用league/commonmark包
• Berlioz\DocParser\Parser\reStructuredText：解析reStructuredText文件，使用gregwar/rst包

您也可以创建自己的解析器，只需实现Berlioz\DocParser\Parser\ParserInterface接口。

如果您需要向特定解析器添加扩展，可以使用一个获取方法来访问原始解析器。Markdown解析器的示例：\Berlioz\DocParser\Parser\Markdown::getCommonMarkConverter()。

您还可以将相应库的相同参数传递给Markdown和reStructuredText构造函数。

缓存

生成文档需要时间，每次请求都生成文档是不可以接受的。

Berlioz\DocParser\DocCacheGenerator类生成已生成和处理的文档缓存，以便快速重用。缓存使用league/flysystem包来存储缓存文件。

使用示例

use Berlioz\DocParser\DocCacheGenerator;
use Berlioz\DocParser\DocGenerator;
use Berlioz\DocParser\Parser\Markdown;
use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;

$version = '1.0';
$cacheFilesystem = new Filesystem(new LocalFilesystemAdapter('/path-of-project/cache'));
$docCacheGenerator = new DocCacheGenerator($cacheFilesystem);

if (null === ($documentation = $docCacheGenerator->get($version))) {
    $docGenerator = new DocGenerator();
    $docGenerator->addParser(new Markdown());
    $documentation =
        $docGenerator->handle(
            $version,
            new Filesystem(new LocalFilesystemAdapter('/path-of-project/doc'))
        );

    $docCacheGenerator->save($documentation);
}

$documentation->handle('path/of/my/page');