百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
D

doctum

> 编程语言
开源

一个 PHP API 文档生成器

357 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

一个 PHP API 文档生成器

Doctum, a PHP API documentation generator. Fork of Sami

Curious about what Doctum generates? Have a look at the MariaDB MySQL Kbs_ or Laravel_ documentation.

Our badges

.. image:: https://img.shields.io/badge/GitHub%20marketplace%20action-available-green.svg :alt: GitHub marketplace action :target: https://github.com/marketplace/actions/action-doctum

.. image:: https://codecov.io/gh/code-lts/doctum/branch/main/graph/badge.svg?branch=main :alt: Project code coverage by Codecov :target: https://codecov.io/gh/code-lts/doctum

.. image:: https://github.com/code-lts/doctum/actions/workflows/tests.yml/badge.svg?branch=main :alt: Project test suite :target: https://github.com/code-lts/doctum/actions/workflows/tests.yml

Installation

.. caution::

Doctum requires **PHP 8.1** or later.

Get Doctum as a phar file_:

.. code-block:: bash

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

You can also find some alternative phar versions:

  • major
  • major. minor (any version since 5.1)
  • major. minor. patch
  • latest _
  • dev _ (not always up to date)
  • major-dev
  • major. minor-dev (most of the time it exists)
  • major. minor. patch-dev (sometimes it exists)

.. code-block:: bash

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

Check that everything worked as expected by executing the doctum.phar file without any arguments:

.. code-block:: bash

$ doctum.phar

Since 5.3.0 the phar does not require to use php keyword anymore because the shebang was added to the phar file. You can now call doctum.phar directly after adding execution rights onto the file.

You can use our GitHub marketplace action _ into your GitHub CI.

Configuration

Before generating documentation, you must create a configuration file. Here is the simplest possible one:

.. code-block:: php

files()
    ->name('*.php')
    ->exclude('Resources')
    ->exclude('Tests')
    ->in('/path/to/yourlib/src');

return new Doctum($iterator);

The Doctum constructor optionally takes an array of options as a second argument:

.. code-block:: php

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
]);

And here is how you can configure different versions:

.. code-block:: php

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
]);

And here is how you can configure a footer link below the Doctum link:

All footer_link keys are optional.

.. code-block:: php

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',
    ],
]);

To enable OpenSearch _ feature in your users browsers:

.. code-block:: php

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
]);

You can find more configuration examples under the examples/ directory of the source code.

Doctum only documents the public API (public properties and methods); override the default configured filter to change this behavior:

.. code-block:: php

 'my-theme-name',
    // Add the path to the theme/themes
    'template_dirs' => [__DIR__ . '/themes/my-theme-name'],
    // [...]
    ]
);

Search Index


The autocomplete and search functionality of Doctum is provided through a
search index that is generated based on the classes, namespaces, interfaces,
and traits of a project. You can customize the search index by overriding the
``search_index_extra`` block of ``doctum.js.twig``.

The ``search_index_extra`` allows you to extend the default theme and add more
entries to the index. For example, some projects implement magic methods that
are dynamically generated at runtime. You might wish to document these methods
while generating API documentation and add them to the search index.

Each entry in the search index is a JavaScript object that contains the
following keys:

type
    The type associated with the entry. Built-in types are "Class",
    "Namespace", "Interface", "Trait". You can add additional types specific
    to an application, and the type information will appear next to the search
    result.

name
    The name of the entry. This is the element in the index that is searchable
    (e.g., class name, namespace name, etc).

fromName
    The parent of the element (if any). This can be used to provide context for
    the entry. For example, the fromName of a class would be the namespace of
    the class.

fromLink
    The link to the parent of the entry (if any). This is used to link a child
    to a parent. For example, this would be a link from a class to the class
    namespace.

doc
    A short text description of the entry.

One such example of when overriding the index is useful could be documenting
dynamically generated API operations of a web service client. Here's a simple
example that adds dynamically generated API operations for a web service client
to the search index:

.. code-block:: twig

    {% 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 %}

This example assumes that the template has a variable ``operations`` available
which contains an array of operations.

.. note::

    Always include a trailing comma for each entry you add to the index. Doctum
    will take care of ensuring that trailing commas are handled properly.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

PHPdoctumdocumentationdocumentation-generatorlong-term-support

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言