README

简单地编写漂亮的API文档。

本项目是原始的 Documentarian PHP移植版本的Slate API文档工具的分支。这个分支将允许您为多个API版本构建API文档。

如果你不喜欢PHP，而是更倾向于nodeJS，为什么不试试Whiteboard呢？

安装

要全局安装Documentarian，请运行

    $ composer global require elevenlab/documentarian

创建文档

要创建一个文档项目，请运行

    $ documentarian create <folder>

如果没有指定 folder，则文档将创建在当前工作目录中。

示例

    $ documentarian create kittens-api

为特定API版本创建文档

要创建特定API的文档，请运行以下命令

    $ documentarian create_version <documentation-folder> <version-name>

在 <documentation-folder>/source/<version-name> 中将创建一个名为 <version-name> 的文件夹。编辑该文件夹中的 index.md 文件以自定义您的特定API文档。

示例

    $ documentarian create_version kittens-api v1
    $ documentarian create_version kittens-api v2

生成文档页面

要生成特定API文档的 .html 文件，请运行以下命令

    $ documentarian generate <folder>

其中 <folder> 是您的文档父文件夹。这将创建一个包含前端资源（如CSS和JavaScript）以及生成的API文档版本的 .html 页面的 public 文件夹。

示例

    $ documentarian generate kittens-api

上述命令将在 kittens-api 中创建一个 public 文件夹，包含以下内容

• css 文件夹 - 包含样式资源
• images 文件夹 - 包含文档中使用的图像
• js 文件夹 - 包含文档页面使用的JavaScript脚本
• v1.html 文件 - API版本 v1 的文档页面
• v2.html 文件 - API版本 v2 的文档页面

更改模板结构

如果您想更改文档文件模板，请编辑文件 <documentation-foler>/views/index.blade.php。

设置版本链接

要设置指向正确API版本文档页面的版本链接，请编辑 index.md 中的 version 部分

versions:
  v1:
    link: v1.html
    target: _blank
  v2:
    name: latest
    link: v2.html

对于每个版本，您可以设置以下参数

• link - 文档页面的链接（href）
• target - href 链接的目标（见 HTML目标属性）
• name - 要在渲染的页面上显示的定制版本名称，留空则使用纯版本名称

深入文档

有关如何自定义主题和其他方面的进一步文档，请参阅官方whiteboard 文档。

Slate / Whiteboard 兼容性

由于Documentarian和Slate都使用常规markdown文件来渲染API文档，因此您现有的Slate API文档应该能够正常工作。如果您遇到任何问题，请提交问题。

贡献者

Slate 由 Robert Lord 在 TripIt 期间构建。

Documentarian 由 Marcel Pociot 构建。

多版本Documentarian由 Valerio Cervo 在 Eleven 构建。