li₃ docs
Once installed in your existing application, however, it generates documentation from your app's docblocks in real-time, which is all accessible from http://yourapp.tld/docs/. Not only that, but it will generate documentation for your plugins, too. Including itself; so it is self-replicating in a way. In this vein, it becomes part of a series of plugins required in order to obtain various documentation volumes of interest.
Such as:
So the documentation plugin is a tool for creating automatically browse-able documentation of your application's codebase. In addition to simple descriptions and tables of contents,
Note: li3_docs
is a plugin, NOT an app. Furthermore, by itself it is a VIEWER ONLY and
contains no actual documentation other than its own.
Installation
- To install run
composer require unionofrad/li3_docs
. - The plugin needs a configured
default
connection. - 2 tables need to be created using
schema.sql
file.
Documentation structure
For generating documentation, li3_docs relies on PHP documentation blocks, or docblocks.
These docblocks can appear above classes, methods, properties, etc., and contain three
things: a short description, a longer description (often including usage examples), and
docblock tags, which are denoted by an @
symbol, followed by a keyword. A typical
docblock might look something like this:
/**
* 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;
This docblock documents a class property, and contains a short description and two
docblock tags. The tags to be used in a docblock vary by what is being documented. A
property docblock should contain a @var
tag that describes what type of value the
property holds, while methods have a series of @param
tags and a @return
tag.
There are also general tags which can be added to any docblock. These include the @see
tag, which allows you to link to another class, method or property, and the @link
tag,
which allows you to link to an arbitrary URL.
Markdown syntax
Docblock descriptions are written in Markdown format, with a few conventions. Namely, any
code references or identifiers should be enclosed in backticks. This includes namespaces,
classes, variable names, and keywords like true
, false
and null
. Extended code
examples should be written enclosed in three sets of backticks, i.e.: `‍
// Code
goes here
``.
Indexing
The plugin supports both manual-like repositories holding markdown formatted files,
as well as source-code repositories, which may additionally have so called namespace
documents (a README.md
files nested inside directories).
The following registers 2 indexes, one for our manual, one for the frameowork 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'
]);
Once registered the index can be regenerated by running the following command.
li3 docs index
Searching
The plugin supports symbol-based search i.e. via ElasticSearch. Search for classes, methods and properties. To get all symbols available in all libraries registered with li3 execute the following method.
use li3_docs\models\Symbols;
foreach (Symbols::harvest($index) as $symbol) {
ElasticSearch::addToIndex($symbol->data());
}
Classes
- li3_docs\controllers\ApisController
- li3_docs\controllers\BooksController
- li3_docs\controllers\DocsController
- li3_docs\doc\Docblock
- li3_docs\doc\UorMarkdown
- li3_docs\doc\Visitor
- li3_docs\extensions\command\Docs
- li3_docs\extensions\helper\Markdown
- li3_docs\models\Indexes
- li3_docs\models\Pages
- li3_docs\models\Symbols