unionofrad/li3_docs

An API and wiki-like documentation generator.

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., _(*1)

Such as:, _(*2)

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

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,, _(*3)

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., _(*4)

Installation

1. To install run composer require unionofrad/li3_docs.
2. The plugin needs a configured default connection.
3. 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:, _(*5)

    /**
     * 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., _(*6)

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., _(*7)

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 ```., _(*8)

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)., _(*9)

The following registers 2 indexes, one for our manual, one for the frameowork API., _(*10)

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., _(*11)

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., _(*12)

use li3_docs\models\Symbols;

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