README

使用 Sphinx 从 PHP 代码内部构建文档。

先决条件

详细使用说明

作为 require-dev 添加

composer require --dev jakota/documentation-builder

在项目根目录下创建与 Documentation 相同的文档文件夹

mkdir ./Documentation

将文档块（即 DocBlocks）添加到您的 PHP 文件中

项目需要一个 Index.rst 来开始。

将以下注释添加到文件中。
通常是主类或起始文件夹中的文件。
这个注释的位置不重要，但不得出现超过一次。

<?php
/** Documentation:Start:Index.rst.
 *
 *Welcome to Your documentation index!
 *====================================
 *
 *.. toctree::
 *   :maxdepth: 2
 *   :caption: Contents:
 *
 *TocTreeInsert
 *
 *Documentation:End
 */

您可以根据需要编辑文本，但不能删除 TocTreeInsert 占位符。

接下来，您想在 PHP 代码中添加更多的 DocBlocks。

<?php

/** Documentation:Start:TocTree:Demo/Index.rst.
 *
 *Demo Class with cool new features
 *=================================
 *
 *.. toctree::
 *   :maxdepth: 2
 *   :caption: Contents:
 *
 *
 *Documentation:End
 */
class DemoController {

在

/** Documentation:Start:TocTree:Demo/Index.rst.

和

 *Documentation:End
 */

之间的每一行（不含前导 *）将被复制到 Demo/Index.rst 文件中。
如果设置了 TocTree:，此文件也将被添加到主 Index.rst 的 TocTree 中。

您可以在文件中的任何位置添加多个 DocBlocks。
但重要的是每个 DocBlock 的每一行的缩进必须保持相同。

配置 JSON

在您的项目根目录中创建一个用于配置 json 和静态文件的文件夹，并命名您喜欢的名称。

一个推荐的文件夹结构如下所示

--- Project-Root
 |--- .documentation        // folder for the config
 | |- _static               // folder for the static content like images
 | |- _templates            // folder for templates
 | |- documentation.json    // config json
 |- Documentation           // folder for the finished documentation

此 documentation.json 文件的内容如下所示

{
  "StartFolder": "Classes",
  "DocumentationFolder": "Documentation",
  "DocumentationType": "html",
  "Favicon": "_static/favicon.svg",
  "Project": "Your Awesome Project Name",
  "Copyright": "2023, Your company or Name",
  "Author": "Your company or Name",
  "Release": "1.2.3",
  "StaticFolder": "_static",
  "TemplatesFolder": ""
}

StartFolder 和 DocumentationFolder 是相对于 Project-Root 的。
StaticFolder 和 TemplatesFolder 是相对于配置文件夹的。

再次，您可以根据需要编辑配置。
但目前为止，仅支持 html 作为 DocumentationType。
如果配置不符合预期，您将看到错误消息。

从您的项目根目录运行构建脚本

./vendor/bin/documentation-builder {the-path-and-file-name-of-your-config.json}

例如

./vendor/bin/documentation-builder .documentation/documentation.json

jakota / documentation-builder

维护者

详细信息