README

Laravel 的 Documenter 是 Documenter for PHP 的扩展和包装器，用于动态生成使用 Laravel 5.4+ 的文档网站。您可以使用 Laravel Documenter 仅作为读取项目 PHP 文件的手段；然而，如果您是这个目标，Documenter for PHP 或 phpDocumentor 可能更符合您的要求。

获取 (Composer)

composer require 8fold/documenter-laravel

或者将以下内容添加到您的 composer.json 文件的 required 部分

composer require "8fold/documenter-laravel": "*"

并将以下内容添加到您的 composer.json 文件的 PSR-4 部分 (注意：第一部分，我认为可以由您选择)

"Eightfold\\DocumenterLaravel\\": "vendor/8fold/documenter-laravel/src/",

建议运行 composer update，即使您已经运行了 $ composer require。

$ composer update

还建议显式运行 NPM

$ npm update

然后发布供应商资产

$ php artisan vendor:publish

现在您可以设置一切了。

启动

在设置方面，Documenter 更倾向于约定胜于配置。因此，将文件放入文件夹，而不是大量操作配置文件。

在您的 /config/app.php 文件的 providers 下注册服务提供者

Eightfold\DocumenterLaravel\DocumenterServiceProvider::class

注意：供应商和包名称在您的 composer.json 中设置。

路由：Documenter 并不试图成为您 Laravel 项目的核心目的。因此，默认使用的路由包含一个名为 developer 的子域名。但是，您应该能够通过复制组内的路由来覆盖此设置，并继续使用默认的 ProjectsController.php。

Documenter 主要：在您的项目中创建一个文件夹，用于放置您希望生成 API 的文件。默认是 /base-laravel-app/app_docs。您可以在 /config/documenter-laravel.php 中更改此设置。

项目文件夹：在每个您希望 Documenter 处理的项目下创建一个文件夹。此文件夹将包含所有版本。文件夹名称应为斜杠形式。例如 documenter-laravel。

版本文件夹：在项目文件夹内创建一个表示版本的文件夹。版本名称应采用斜杠形式。例如 v1-0-0。这是您放置要处理的代码的文件夹级别。默认情况下，Documenter 将其处理限制在当前级别的 src 目录。

Sass：如果您正在使用默认的外观和相关的模板，请 @import 相关的 Sass 文件

@import 'vendor/8fold/documenter/documenter';

到此为止，您应该已经准备就绪。如果这看起来不完整（可能缺少 JavaScript），请纠正或 提交问题。谢谢！

配置

documenter_domain：要使用的域名。建议在 .env 中将其设置为变量。《DOCUMENTER_DOMAIN》是默认使用的变量名称。

projects_root：默认为 Laravel 项目的根目录下的 app_docs。这将在 Laravel 的主 app 目录下直接放置该文件夹。

项目：这是一个大项目，但希望它很简单。Documenter 将仅限于列出在这里的项目。字典键应与设置时选择的项目的 slug 匹配。值是一个包含 "title" 和 "category" 键的字典，其中 "title" 的值是项目的人类友好字符串，"category" 是用于分类项目的人类友好字符串。"category" 键是可选的（我认为是）。所以，举个例子，让我们使用适用于 Laravel 5.4+ 的 Documenter。

'project' => [
    'documenter-php' => [
        'title' => 'Documenter for Laravel 5.4+',
        'category' => 'Documentation generators'
    ]
]

这意味着 Documenter 预期以下（使用默认设置）

/app_docs
    /documenter-php
        /v1-0-0
        /...

视图

如果您已经完成了前面的步骤，在这个时候，您应该能够生成一个网站。但是，它可能不符合您期望的外观和感觉。Documenter 尝试使其变得简单（或者至少更容易）。您将使用所有您习惯的 Laravel 功能；这里不需要学习很多新事物。

我们再次尝试使用约定优于配置。

当您运行 $ php artisan vendor:publish 时，主目录中的 /resources/views 位置将生成一个 "documenter" 文件夹。最初它是一个空目录，您可以将文件和文件夹放入这个目录中，以便告诉 Documenter 使用哪些视图以及何时使用。让我们从最定制的视图开始。

/resources/views/documenter
  /documenter-php
    /v1-0-0
      home.blade.php
      method.blade.php
      object.blade.php
      property.blade.php
    projectOverview.blade.php
  documenterIndex.blade.php

• documenterIndex：Documenter 假设这个模板用于列出所有项目，并允许用户导航到其中的一个。
• projectOverview：Documenter 假设这个模板用于列出项目可用的所有版本，可选地包括描述和其他资源。
• home：Documenter 假设这个模板用于列出项目版本中所有的类、特性和接口，可选地包括描述和其他资源。
• object：Documenter 假设这个模板用于列出类、特性和接口的属性和方法。
• 方法和属性：Documenter 假设这些模板显示项目中的方法或属性的文档。

此设置允许您为项目版本创建特定的布局。也可以为所有项目创建通用的模板，无论版本如何。

/resources/views/documenter
  /version
    home.blade.php
    method.blade.php
    object.blade.php
    property.blade.php
  projectOverview.blade.php
  documenterIndex.blade.php

现在，任何由 Documenter 考虑的项目都将使用这些模板。每个模板的假定目的不会改变。注意：这是 Documenter 的默认设置。

如果您没有使用 projectOverview 模板，Documenter 将尝试将用户重定向到项目的最高版本的主页（默认情况下，Documenter 不包括 projectOverview 模板）。

总结一下，Documenter 首先在项目版本下查找模板文件。如果没有找到，它将在您的 /resources/views/documenter 和 /resources/views/documenter/version 目录中查找模板。如果没有找到，它将使用自己的模板。

如果这看起来不完整或与您的体验不符，请纠正或 提交问题。谢谢！