README

好奇Doctum生成的效果？请查看MariaDB MySQL Kbs或Laravel文档。

我们的徽章

安装

注意！

Doctum需要PHP 7.2.20或更高版本。

获取Doctum的phar文件

$ curl -O https://doctum.long-term.support/releases/latest/doctum.phar

您还可以找到一些替代的phar版本

主要
major. minor (自5.1以来的任何版本)
major. minor. patch
最新版本
dev（不一定是最新的）
major-dev
major. minor-dev（通常存在）
major. minor. patch-dev（有时存在）

$ curl -O https://doctum.long-term.support/releases/${version}/doctum.phar && chmod +x doctum.phar

通过执行不带任何参数的doctum.phar文件来检查一切是否按预期工作

$ doctum.phar

从5.3.0版本开始，phar不再需要使用php关键字，因为已经在phar文件中添加了shebang。现在，您可以直接在文件上添加执行权限后调用doctum.phar。

您可以在GitHub CI中使用我们的GitHub marketplace action。

配置

在生成文档之前，您必须创建一个配置文件。以下是最简单的配置示例

<?php

return new Doctum\Doctum('/path/to/yourlib/src');

配置文件必须返回一个Doctum\Doctum实例，构造函数的第一个参数是您想要生成文档的代码的路径。

实际上，您可以使用任何有效的PHP迭代器（并且根据这一点，任何Symfony Finder类的实例）

<?php

use Doctum\Doctum;
use Symfony\Component\Finder\Finder;

$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in('/path/to/yourlib/src');

return new Doctum($iterator);

Doctum构造函数可以接受一个数组作为第二个参数，作为选项

return new Doctum($iterator, [
    'title'                => 'yourlib API',
    'language'             => 'en', // Could be 'fr'
    'build_dir'            => __DIR__ . '/build',
    'cache_dir'            => __DIR__ . '/cache',
    'source_dir'           => '/path/to/repository/',
    'remote_repository'    => new GitHubRemoteRepository('username/repository', '/path/to/repository'),
    'default_opened_level' => 2, // optional, 2 is the default value
]);

以下是配置不同版本的方法

<?php

use Doctum\Doctum;
use Doctum\RemoteRepository\GitHubRemoteRepository;
use Doctum\Version\GitVersionCollection;
use Symfony\Component\Finder\Finder;

$dir = '/path/to/yourlib/src';
$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in($dir);

// generate documentation for all v2.0.* tags, the 2.0 branch, and the main one
$versions = GitVersionCollection::create($dir)
    // In a non case-sensitive way, tags containing "PR", "RC", "BETA" and "ALPHA" will be filtered out
    // To change this, use: `$versions->setFilter(static function (string $version): bool { // ... });`
    ->addFromTags('v2.0.*')
    ->add('2.0', '2.0 branch')
    ->add('main', 'main branch');

return new Doctum($iterator, [
    'versions'             => $versions,
    'title'                => 'yourlib API',
    'language'             => 'en', // Could be 'fr'
    'build_dir'            => __DIR__ . '/../build/sf2/%version%',
    'cache_dir'            => __DIR__ . '/../cache/sf2/%version%',
    'source_dir'           => dirname($dir) . '/',
    'remote_repository'    => new GitHubRemoteRepository('yourorg/yourlib', dirname($dir)),
    'default_opened_level' => 2, // optional, 2 is the default value
]);

以下是配置Doctum链接下方页脚链接的方法

所有footer_link键都是可选的。

<?php

use Doctum\Doctum;
use Symfony\Component\Finder\Finder;

$dir = '/path/to/yourlib/src';
$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in($dir);

return new Doctum($iterator, [
    'title'                => 'yourlib API',
    'source_dir'           => dirname($dir) . '/',
    'remote_repository'    => new GitHubRemoteRepository('yourorg/yourlib', dirname($dir)),
    'footer_link'          => [
        'href'        => 'https://github.com/code-lts/doctum',
        'rel'         => 'noreferrer noopener',
        'target'      => '_blank',
        'before_text' => 'You can edit the configuration',
        'link_text'   => 'on this', // Required if the href key is set
        'after_text'  => 'repository',
    ],
]);

要启用用户浏览器中的OpenSearch功能

<?php

use Doctum\Doctum;
use Symfony\Component\Finder\Finder;

$dir = '/path/to/yourlib/src';
$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in($dir);

return new Doctum($iterator, [
    'title'    => 'Project Api Documentation',
    // Necessary to enable the opensearch.xml file generation
    'base_url' => 'https://apidocs.company.tld/',
    // If you have a favicon
    // 'favicon' => 'https://company.tld/favicon.ico',
    // ... more configs
]);

您可以在源代码的examples/目录下找到更多配置示例。

Doctum仅记录公共API（公共属性和方法）；要更改此行为，请覆盖默认配置的filter

<?php

use Doctum\Parser\Filter\TrueFilter;

$doctum = new Doctum(...);
// document all methods and properties
$doctum['filter'] = function () {
    return new TrueFilter();
};

渲染

现在我们已经有了配置文件，让我们生成API文档

$ doctum.phar update /path/to/config.php

生成的文档可以在配置的build/目录下找到（请注意，由于JavaScript执行限制，客户端搜索引擎在Chrome上无法工作，除非Chrome以"--allow-file-access-from-files"选项启动 -- 它在Firefox中运行良好）。

默认情况下，Doctum配置为在"增量"模式下运行。这意味着在运行update命令时，Doctum只重新生成自上次执行以来代码更改所需的文件。

Doctum还可以检测您的phpdoc中的问题，并在您添加-v选项时告诉您需要修复的内容。

$ doctum.phar update /path/to/config.php -v

创建主题

如果默认主题不符合您的需求，您可以非常容易地创建一个新的主题，或者简单地覆盖现有的主题。

主题只是一个包含描述主题的manifest.yml文件的目录（这是一个YAML文件）。

name:   markdown-custom
parent: default

上述配置基于内置的default主题创建了一个新的markdown-custom主题。要覆盖模板，只需创建一个与原始模板同名的文件。例如，以下是如何扩展默认类模板，在类页面标题中给类名添加“类”前缀的方法。

{# pages/class.twig #}

{% extends 'default/pages/class.twig' %}

{% block title %}Class {{ parent() }}{% endblock %}

如果您熟悉Twig，您将能够非常容易地调整模板的每个方面，因为所有内容都已经被很好地隔离在命名的Twig块中。

主题还可以添加更多模板和静态文件。以下是默认主题的清单。

name: default

static:
    'css/doctum.css': 'css/doctum.css'
    'css/bootstrap.min.css': 'css/bootstrap.min.css'
    'css/bootstrap-theme.min.css': 'css/bootstrap-theme.min.css'
    'fonts/doctum-font.css': 'fonts/doctum-font.css'
    'fonts/doctum.woff': 'fonts/doctum.woff'
    'fonts/doctum.woff2': 'fonts/doctum.woff2'
    'fonts/doctum.ttf': 'fonts/doctum.ttf'
    'fonts/doctum.svg': 'fonts/doctum.svg'
    'fonts/doctum.eot': 'fonts/doctum.eot'
    'js/jquery-3.5.1.slim.min.js': 'js/jquery-3.5.1.slim.min.js'
    'js/bootstrap.min.js': 'js/bootstrap.min.js'
    'js/autocomplete.min.js': 'js/autocomplete.min.js'

global:
    'index.twig':      'index.html'
    'doc-index.twig':  'doc-index.html'
    'namespaces.twig': 'namespaces.html'
    'classes.twig':    'classes.html'
    'interfaces.twig': 'interfaces.html'
    'traits.twig':     'traits.html'
    'opensearch.twig': 'opensearch.xml'
    'search.twig':     'search.html'
    'doctum.js.twig':  'doctum.js'

namespace:
    'namespace.twig': '%s.html'

class:
    'class.twig': '%s.html'

文件包含在部分中，具体取决于Doctum如何处理它们。

static：文件按原样复制（例如，图像、样式表或JavaScript文件等资产）。
global：不依赖于当前类上下文的模板。
namespace：为每个命名空间应生成的模板。
class：为每个类应生成的模板。

主题配置

<?php

return new Doctum($iterator, [
    // [...]
    'theme'         => 'my-theme-name',
    // Add the path to the theme/themes
    'template_dirs' => [__DIR__ . '/themes/my-theme-name'],
    // [...]
    ]
);

搜索索引

Doctum的自动完成和搜索功能通过一个基于项目类、命名空间、接口和特性生成的搜索索引提供。您可以通过覆盖doctum.js.twig中的search_index_extra块来自定义搜索索引。

search_index_extra允许您扩展默认主题并向索引添加更多条目。例如，一些项目实现了在运行时动态生成的魔法方法。您可能希望在生成API文档时记录这些方法并将它们添加到搜索索引中。

搜索索引中的每个条目都是一个包含以下键的JavaScript对象：

type: 与条目关联的类型。内置类型是“Class”，“Namespace”，“Interface”，“Trait”。您可以添加特定于应用程序的附加类型，类型信息将出现在搜索结果旁边。
name: 条目的名称。这是索引中可搜索的元素（例如，类名、命名空间名等）。
fromName: 元素的父元素（如果有的话）。这可以用于为条目提供上下文。例如，类的fromName将是类的命名空间。
fromLink: 条目的父元素的链接（如果有的话）。这用于将子元素链接到父元素。例如，这将是类到类命名空间的链接。
doc: 条目的简短文本描述。

覆盖索引的一个有用的例子可能是记录动态生成的Web服务客户端的API操作。以下是一个简单的示例，它将Web服务客户端的动态生成的API操作添加到搜索索引中。

{% extends "default/doctum.js.twig" %}

{% block search_index_extra %}
    {% for operation in operations -%}
        {
            type: 'Operation'|trans,
            link: operation.path,
            name: operation.name,
            doc: operation.doc,
        }|json_encode|raw
    {%- endfor %}
{% endblock %}

此示例假设模板中有一个名为operations的变量，它包含一个操作数组。

注意

为索引中添加的每个条目始终包含一个尾随逗号。Doctum将负责确保尾随逗号得到适当的处理。

code-lts / doctum

维护者

详细信息

README

我们的徽章

安装

配置

渲染

创建主题

主题配置

搜索索引