README

一旦安装到现有的应用中，它将实时从应用文档块中生成文档，所有内容都可以在 http://yourapp.tld/docs/ 访问。不仅如此，它还会为您的插件生成文档，包括自身；因此，它以一种自我复制的方式存在。在这方面，它成为了一系列插件的一部分，这些插件是为了获取各种感兴趣的文档量所必需的。

例如

• https://github.com/UnionOfRAD/manual
• https://github.com/UnionOfRAD/lithium

所以，文档插件是创建应用程序代码库可自动浏览文档的工具。除了简单的描述和目录表之外，

注意: li3_docs 是一个 插件，而不是应用程序。此外，它本身仅是一个查看器，不包含除自身以外的任何实际文档。

安装

1. 要安装，请运行 composer require unionofrad/li3_docs。
2. 插件需要一个配置好的 default 连接。
3. 需要使用 schema.sql 文件创建2个表。

文档结构

为了生成文档，li3_docs 依赖于PHP文档块，或称为 docblocks。这些docblocks可以出现在类、方法、属性等上方，并包含三个东西：简短描述、较长的描述（通常包括使用示例）和docblock 标签，这些标签由一个@符号和一个关键字组成。一个典型的docblock可能看起来像这样

	/**
	 * Contains an instance of the `Request` object with all the details of the HTTP request that
	 * was dispatched to the controller object. Any parameters captured in routing, such as
	 * controller or action name are accessible as properties of this object, i.e.
	 * `$this->request->controller` or `$this->request->action`.
	 *
	 * @see lithium\action\Request
	 * @var object
	 */
	public $request = null;

这个docblock记录了一个类属性，包含简短描述和两个docblock标签。docblock中使用的标签根据所记录的内容而有所不同。属性docblock应包含一个@var标签，描述属性所持有的值类型，而方法则有一系列@param标签和一个@return标签。

还可以添加到任何docblock中的通用标签。这些包括@see标签，允许您链接到另一个类、方法或属性，以及@link标签，允许您链接到任意URL。

Markdown语法

docblock描述是用Markdown格式编写的，有一些约定。具体来说，任何代码引用或标识符都应放在反引号中。这包括命名空间、类、变量名称以及true、false和null等关键字。扩展代码示例应写在外围的反引号中，即：‍ // 代码在这里 ```。

索引

插件支持类似于手册的存储库，这些存储库包含Markdown格式的文件，以及源代码存储库，这些存储库可能还包含所谓的命名空间文档（目录内部的README.md文件）。

以下注册了2个索引，一个用于我们的手册，一个用于框架API。

use li3_docs\models\Indexes;

Indexes::register([
	'type' => 'book',
	'title' => 'li₃: The Definitive Guide',
	'name' => 'manual',
	'version' => '1.x',
	'path' => '/tmp/manual_1',
]);

Indexes::register([
	'type' => 'api',
	'title' => 'Framework API',
	'name' => 'lithium',
	'version' => '1.0.x',
	'path' => '/tmp/lithium_10',
	'namespace' => 'lithium'
]);

注册索引后，可以通过运行以下命令重新生成索引。

li3 docs index

搜索

插件支持基于符号的搜索，即通过ElasticSearch。搜索类、方法和属性。要获取所有在li3注册的库中可用的符号，请执行以下方法。

use li3_docs\models\Symbols;

foreach (Symbols::harvest($index) as $symbol) {
	ElasticSearch::addToIndex($symbol->data());
}