README

Peridocs 是一个 Peridot 插件，可以从您的 Peridot 测试中自动生成 Markdown 文档。我发现我的 Peridot 测试通常是最佳文档来源。该项目允许您以自动化方式利用测试文档。

安装

使用 composer 将其作为开发依赖项加载： krak/peridocs。

在您的 peridot.php 配置文件中，添加以下内容

<?php

use Krak\Peridocs;

return function($emitter) {
    // the second parameter is optional and is used to configure the DocsContext
    Peridocs\bootstrap($emitter, function() {
        return new DocsContext(null, [
            'headerFmt' => '<h3 id="{id}">{signature}</h3>',
            'showLinks' => false,
            'nsPrefix' => 'Acme\\Prefix\\',
            'numTableRows' => 4,
        ]);
    });
};

使用方法

一旦注册，您可以在测试中使用 docFn 函数来为给定测试启用文档。

// function to test
function addMaybe(int $a, int $b): int {
    return $a == $b ? $a * $a : $a + $b;
}

// in some spec.php file
describe('Demo Package', function() {
    describe('addMaybe', function() {
        docFn(addMaybe::class); // this is the fully qualified name for the function e.g. 'Acme\Prefix\addMaybe'
        docIntro('`addMaybe` optional foreword/introduction.');

        it('usually adds two numbers together', function() {
            expect(addMaybe(1, 2))->equal(3);
        });
        it('but will multiply the two numbers when they are equal', function() {
            expect(addMaybe(3, 3))->equal(9);
        });

        docOutro('This is the optional outro/conclusion to be appended to the text');
    });
});

现在，您可以通过运行带有 peridocs 报告器的 peridot 来生成 Markdown。

./vendor/bin/peridot -r peridocs

它应该输出以下 Markdown

<h3 id="api-krak-peridocs-addmaybe">addMaybe(int $a, int $b): int</h3>

**Name:** Krak\Peridocs\addMaybe

`addMaybe` optional foreword/introduction.

usually adds two numbers together:

```php
expect(addMaybe(1, 2))->equal(3);
```

but will multiply the two numbers when they are equal:

```php
expect(addMaybe(3, 3))->equal(9);
```

This is the optional outro/conclusion to be appended to the text