编程

如何为 Laravel 项目生成文档

64 2025-03-29 16:09:00

在软件开发中，编写代码只是一个开始。真正使卓越项目与众不同的一点是其文档的质量。

清晰、组织良好的文档不仅增强了开发人员/项目利益相关者之间的协作，还为最终用户提供了宝贵的指导，使产品更易于访问和使用。

对于 Laravel 项目，无论你是在构建一个简单的应用、API 还是一个面向用户的产品，出色的文档都是必不可少的，幸运的是，有很多工具可以帮助你做到这一点。

本文中，我们将探讨如何使用 Scribe、PHPDoc、Jigsaw 和 Docusaurus 等工具为 Laravel 项目创建高质量的文档，以满足开发人员和产品用户的需求。

让我们潜入水中。👇

为什么好的文档很重要

好的文档帮助：

  • 引导新开发人员: 它为建立和理解项目提供了明确的指导。
  • 引导产品用户: 编写良好的用户指南和教程可以帮助用户毫无困惑地充分利用你的产品。
  • 维护: 适当的文档可以帮助你和其他人了解项目的结构，使调试和更新更容易。
  • 合作: 清晰的文档促进高效协作，无论是在开源项目还是团队项目上。
  • 减少工单: 全面、易于遵循的文档使用户能够自行解决常见问题，从而减少支持请求的数量。

1. 使用 Scribe 生成 API 文档

对于暴露 API 的项目，自动生成 API 文档将为你省去很多麻烦。Scribe 是一个特定于 Laravel 的软件包，它根据您的路由和注释生成 API 文档。

安装及使用 Scribe

通过 Composer 安装：

composer require knuckleswtf/scribe

发布配置文件和生成文档：

php artisan vendor:publish --tag=scribe-config

生成文档：

php artisan scribe:generate

Scribe 扫描路由并生成 Markdown 或 HTML 格式的 API 文档，你可以将其作为项目的一部分或在线托管。在控制器中使用注释可提供有关 API 的更多详细信息：

/**
 * @group Users
 * 
 * Retrieve a list of users.
 * 
 * @response 200 {
 *   "id": 1,
 *   "name": "John Doe",
 *   "email": "john@example.com"
 * }
 */
public function index()
{
    return User::all();
}

请查阅 Scribe 的文档 - 它是使用 Docusaurus 生成的 :) 

2. 使用 PHPDoc 和 phpDocumentor 生成代码级文档

除了 API 文档之外，你可能还需要内联文档来解释方法和类级别的代码。这就是 PHPDoc 发挥作用的地方。PHPDoc 注释提供了对特定方法、属性和类的作用的见解。

使用 PHPDoc

以下是使用 PHPDoc 的一个示例：

/**
 * Store a newly created user in the database.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return \Illuminate\Http\JsonResponse
 */
public function store(Request $request)
{
    $request->validate([
        'name' => 'required',
        'email' => 'required|email',
    ]);

    $user = User::create($request->all());

    return response()->json($user, 201);
}

你可以说使用 phpDocumentor 从 PHPDoc 注释中生成结构化文档

要使用 PHAR 存档安装它，请从以下位置下载 PHAR 文件 https://github.com/phpDocumentor/phpDocumentor/releases

然后，使用以下命令运行：

php phpDocumentor.phar run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

这将扫描你的代码以查找 PHPDoc 注释，并生成一个完整的 HTML 文档网站。

3. Jigsaw 静态文档站

对于需要更多扩展的自定义文档(例如，解释业务逻辑、安装步骤、配置等)，使用 Jigsaw 这样的静态站点生成器是一个不错的选择。

Jigsaw 设置

Jigsaw 是一个基于 Laravel 的静态站点生成器，易于用于文档。通过 Composer 全局安装 Jigsaw：

composer global require tightenco/jigsaw

然后，初始化文档站：

jigsaw init docs

Jigsaw 创建了一个带有文件夹的框架项目，用于编写 Markdown 内容。编写完文档后，可以使用以下方法构建网站：

jigsaw build

这就生成了可以在任何地方(如Github Pages 或 Netlify)托管的静态 HTML 文件。

4. 使用 Docusaurus 生成全文档网站

如果你想要一个更精致、生产就绪的文档网站，具有版本控制、搜索和漂亮的主题等高级功能，Docusaurus 是一个完美的选择。Docusaurus 是由 Facebook 构建的基于 React 的静态站点生成器，非常适合需要全面、可扩展文档的项目。

为什么使用 Docusaurus?

Docusaurus 提供:

  • Markdown 支持: 就像 Jigsaw，以 Markdown 格式编写文档。
  • 版本化: 支持文档的不同版本，对于多版本发布的项目有用。
  • 搜索: 开箱即用的搜索功能，轻松导航。
  • 国际化: 可以不同语言提供文档。
  • React 组件: 如果你需要交互性或自定义UI元素。

设置 Docusaurus

安装 Docusaurus: 要安装 Docusaurus，运行以下命令：

npx create-docusaurus@latest my-docs-site classic
cd my-docs-site
npm install

配置文档：docs 目录包含文档的 Markdown 文件。 你可以从编辑 docs/intro.md 示例文档或添加新文件开始。

运行开发服务器: 要实时查看文档，可以使用开发服务器：

npm start

Docusaurus 将生成可以预览文档站的本地服务。

编译文档站: 当你准备好构建站点时，使用以下命令生成静态文件：

npm run build

版本化: Docusaurus 支持文档版本化。在发布完项目的新版本后，运行版本化命令如下：

npm run docusaurus docs:version 1.0.0

该命令将生成当前文档的快照，允许你分别维护不同版本的文档。

部署 Docusaurus

你可以在任何静态网站托管平台上部署 Docusaurus，如 GitHub Pages、Netlify 或 Vercel。对于 GitHub 页面：

npm run deploy

此命令将自动将你的静态文件推送到 GitHub 仓库的 gh-pages 分支，并使文档站上线。

在 Laravel 应用中部署 Docusaurus 文档

如果愿意，你可以在 Laravel 项目中托管 Docusaurus 文档。事实上，这就是我托管 SaaSykit 文档的方式。

我将 docusaurus 项目(markdown 文档所在的位置)托管在一个单独的 Github 存储库中。在本地计算机上，这个存储库与 SaaSykit 的网站项目位于同一目录中。

然后，在 docusaurus 项目中的 `package.json` 中，我定义了一个新命令->"build-in-saasykit-website"(如下)

// ....
"scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "build-in-saasykit-website": "docusaurus build --out-dir ../saasykit-website/public/docs",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
// ....

如您所料，此命令使用项目的相对路径在 SaaSykit 网站(Laravel 应用)的 `public/docs` 目录中生成文档静态文件。

npm run build-in-saasykit-website

由于这些文件在 “public” 目录中，用户可以在 web 上访问这些文件。

5. README 及 Markdown 文件

无论使用哪种工具来处理详细文档，都要在项目的存储库中维护一个高质量的 README.md 文件。这应包括：

  • 项目概览: 项目的简单总结。
  • 安装说明：如何安装及运行项目。
  • 使用：示例或者关键命令。
  • 贡献指南: 如果是开源项目，说明如何为项目提供贡献。

基本示例如下：

# My Laravel Project

This is a Laravel project designed to showcase best practices in generating documentation.

## Installation

1. Clone the repository: `git clone https://github.com/yourusername/project.git`
2. Install dependencies: `composer install`
3. Set up your `.env` file.
4. Run migrations: `php artisan migrate`

## Usage

To start the development server, run `php artisan serve`.

小结

文档化 Laravel 项目不一定是一种负担。使用正确的工具，如 Scribe、PHPDoc、Jigsaw 和 Docusaurus，你可以创建清晰、有组织的文档，为开发团队和产品用户服务。

通过投入时间编写和自动化高质量文档的生成，你不仅可以改善协作和简化维护，还可以增强用户体验并减少支持请求，为未来的自己节省大量时间和精力。好的文档不仅仅是一个附加组件，它们是任何项目长期成功的基础。

 

Laravel PHP

相关推荐：

最新文章：

上一篇
下一篇