README

Kitab是PHP程序文档驱动质量的理想伴侣。

由团队用❤️制作

Kitab的目标有两个：渲染和测试文档

根据您的代码生成高质量且可搜索的文档。文档中的内容被编译成静态HTML文件，并带有强大的静态搜索引擎
测试文档本身。确实，文档包含示例，这些示例被编译成测试套件，并直接执行以确保示例仍然是最新的且可正常工作。

Kitab (كتاب) 在阿拉伯语中意为“书”。应读作/kitaːb/。

静态文档

Kitab能够将代码中的文档编译成静态HTML文件。提供精心设计的外观，以确保文档看起来很棒。这允许您自定义标志、项目名称等。

为您的文档专门编译了一个静态搜索引擎。它包含我们从搜索引擎中可以期待的所有现代功能，如分词、词干提取、停用词过滤、词频-逆文档频率（TF-IDF）、倒排索引等。搜索引擎数据库是预先计算并优化以尽可能快速加载的。

您的文档提供的信息越详细、词汇越智能，搜索引擎就越能够提供相关结果。

以下命令行将从src目录中的代码编译文档到存储在doc中的HTML文件

$ ./bin/kitab compile --open --with-composer --output-directory doc src

--with-composer选项告诉Kitab使用Composer进行PSR-4映射定义。这对于将README.md文件映射到命名空间目录非常有用。更多内容请参阅下文。--open选项在文档成功生成后将在默认浏览器中打开。

DocTest

基于文档中存在的示例生成的文档测试套件，也称为DocTest。示例被编译成测试套件并实时执行。生成缓存以避免每次都需要重新编译示例到测试套件。

例如，以下示例将成功执行

/**
 * Classical sum of two integers.
 *
 * # Examples
 *
 * ```php
 * $x = 1;
 * $y = 2;
 *
 * assert(3 === sum($x + $y));
 * ```
 */
function sum(int $x, int $y): int
{
    return $x + $y;
}

以下命令行将生成并执行从src目录生成的文档测试套件

$ ./bin/kitab test src

在幕后，Kitab使用atoum测试框架。

依赖关系

Kitab需要安装PHP和NodeJS：PHP因为这是一个PHP程序，NodeJS用于预编译静态搜索引擎（该搜索引擎是用Elm编写的）。

标准和格式

Kitab期望PHP代码中的文档采用CommonMark（Markdown的一种标准变体）编写。它可以与HTML混合使用。

每个文档块可以声明部分，以及任何类型的CommonMark元素，例如

/**
 * This is a block of documentation, attached to a PHP class.
 *
 * # Examples
 *
 * An example illustrates how to use the documented entity, here the
 * class `C`.
 *
 * ```php
 * $c = new C();
 * ```
 */
class C { }

只有两个特殊的部分名称：示例和异常。使用它们来介绍一个或多个示例和异常说明。这是许多其他工具使用的通用标准。

任何类型的实体都可以进行文档化：类、接口、特质、类属性、常量、方法和函数。

命名空间不能直接从代码中进行文档化，因为它们的声明方式（实体在命名空间内部声明；命名空间不是直接声明的）。然而，可以通过特殊的文件进行文档化，这些文件命名为README.md。如果您的代码遵循PSR-4规范，那么运行Kitab时使用--with-composer选项指定项目composer.json文件的位置，以便Kitab可以自动找到PSR-4映射。这些映射是将命名空间转换为目录路径所必需的。对于每个表示命名空间的目录，如果存在README.md文件，则它将用作特定命名空间的文档。例如，Kitab\映射到src/，因此期望在src/Compiler/README.md文件中找到Kitab\Compiler命名空间的文档。这很简单。使用起来非常直观。

实体和命名空间的文档被插入到它们各自的文档页面顶部。这是介绍。页面其余部分包含有关实体或命名空间的信息。

代码块

文档可以包含代码块。可以通过以下标准符号指定代码块的类型

```type
code
```

其中type可以是php、http、sh、html、css等。

类型有两个影响

它指定了在将文档渲染为HTML时的语法高亮显示
它是潜在代码块处理程序的标识符。代码块处理程序负责将代码块内容编译为有效的测试。

确实，所有示例和异常部分中的代码块都可以通过./bin/kitab test命令编译成测试套件。例如，使用php代码块类型，可以指定测试用例的期望

php表示测试用例必须成功
php,ignore表示测试用例必须被跳过（仅渲染，不测试）
php,must_throw表示测试用例必须抛出任何类型的异常
php,must_throw(E)表示测试用例必须抛出类型为E的异常

因此，以下示例将是一个成功示例

/**
 * Generate a runtime exception.
 *
 * # Examples
 *
 * ```php,must_throw(RuntimeException)
 * panic('Hello World');
 * ```
 */
function panic(string $message): RuntimeException
{
    throw new RuntimeException($message);
}

可扩展性

可以编写特定的代码块处理程序。这意味着可以编写扩展来将文档编译为特定的测试。有关更多信息，请检查Kitab\Compiler\Target\DocTest\CodeBlockHandler\Definition接口和实现。

配置

可以使用外部PHP文件配置Kitab。文件名可自由设置，但我们推荐以下命名：

.kitab.target.html.php 用于配置文档编译为HTML，
.kitab.target.doctest.php 用于配置文档的测试。

两个文件必须分别返回Kitab\Compiler\Target\Html\Configuration和Kitab\Compiler\Target\DocTest\Configuration类的实例。

以下示例演示了一个常见的.kitab.target.html.php文件

$configuration = new Kitab\Compiler\Target\Html\Configuration();

$configuration->defaultNamespace = 'Kitab';
$configuration->logoURL          = 'https://example.org/logo.png';
$configuration->projectName      = 'Kitab';
$configuration->composerFile     = __DIR__ . '/composer.json';

return $configuration;

以下示例演示了一个常见的.kitab.target.doctest.php文件

$configuration = new Kitab\Compiler\Target\DocTest\Configuration();

$configuration->autoloaderFile      = __DIR__ . '/vendor/autoload.php';
$configuration->concurrentProcesses = 4;

return $configuration;

命令kitab compile和kitab test都接受一个名为--configuration-file的选项，用于使用特定的配置文件作为默认值，例如：

$ ./bin/kitab compile --configuration-file .kitab.target.html.php --output-directory doc src

hoa / kitab

维护者

详细信息