Teak

Teak is a CLI utility to generate a Markdown reference documentation for PHP projects (optimized for WordPress).

It can generate documentation for

• Reference pages for your classes and global functions that follow the WordPress PHP Documentation Standards
• Reference for WordPress action and filters hooks that follow the Inline Documentation Standards for Actions and Filters.

You can use documentation generated by Teak to create a documentation website when you use it in combination with a static site generator.

Teak is used to generate the documentation for Timber, which uses Hugo as a static site generator.

• Installation
• CLI Usage
  • Generate a class reference
  • Generate a function reference
  • Generate a hook reference
    • Options
  • Global CLI options
    • File options
    • Front Matter options
• DocBlocks
  • Ignoring Structural Elements
  • Special Tags
    • @example
    • Parameters that are arrays
  • Hook Variations
• Limitations
• Contributing
• Roadmap

Installation

You can install the package with Composer:

composer require timber/teak --dev

CLI Usage

Generate a class reference

When you pass a folder to the Class Reference Generator, it will generate a separate Markdown file for each class that it finds.

Use a folder as the input

vendor/bin/teak generate:class-reference ./lib/ --output ./docs/reference

This searches all the PHP classes in ./lib/ and outputs the Markdown files into ./docs/reference.

Use a single file as the input

vendor/bin/teak generate:class-reference ./lib/Post.php --output ./docs/reference

Generate a function reference

The Function Reference Generator will search all the files for global functions and output them in a single Markdown file.

vendor/bin/teak generate:function-reference ./lib/ --output ./docs/

Generate a hook reference

The Hook Reference Generator will search all the files for WordPress actions or filters and outputs one single Markdown file, with all the hooks found.

vendor/bin/teak generate:hook-reference ./lib --output ./docs/hooks --hook_type=filter
vendor/bin/teak generate:hook-reference ./lib --output ./docs/hooks --hook_type=action

Options

• --hook_type – The hook type to look for. Has to be either filter or action.
• --hook_prefix – Hook prefix (to select only hooks with a certain prefix).

Global CLI options

Display help for commands

vendor/bin/teak generate:class-reference -h
vendor/bin/teak generate:function-reference -h
vendor/bin/teak generate:hook-reference -h

File options

• --file_name – File Name (the .md extension is appended automatically)
• --file_prefix - File Prefix
• --file_title - File Title (Heading 1 in the Markdown document). Only applicable to hooks and functions reference.

Front Matter options

Teak can generate Front Matter Blocks that you will use if you use the generated Markdown files to generate a website using a static site generator.

• --front_matter_style – Front Matter type. Currently, only "YAML" is supported (if not provided, will output a Heading 1 instead of a Front Matter block).

DocBlocks

Teak works best if you follow the WordPress PHP Documentation Standards. Because the documentation renders to Markdown, you can use Markdown syntax in your DocBlocks.

Ignoring Structural Elements

An element (class, method, property) is ignored when one of the following conditions applies:

• No DocBlock is provided
• No @api tag is present
• An @ignore tag is present
• An @internal tag is present
• The visibility is private (applies to methods only)

This means that for Markdown files to be generated for a class at all, you’ll need at least a DocBlock, with an @api tag.

/**
 * Class My_Public_Class
 *
 * @api
 */
class My_Public_Class {}

Special Tags

@example

The @example tag allows you add code examples to your DocBlocks, including fenced code blocks:

/**
 * Function summary.
 * 
 * Function description.
 *
 * @api
 * @example
 *
 * Optional text to describe the example
 * 
 * ```php
 * my_method( 'example', false );
 * ```
 *
 * @param string $param1 Description. Default 'value'.
 * @param bool   $param2 Description. Default true.
 */
function my_method( $param1 = 'value', $param2 = true ) {}

Parameters that are arrays

Teak supports parameters that are arrays.

Hook Variations

Sometimes you’ll have two hooks that follow each other and do basically the same, but allow you to make the hook apply only on certain conditions:

/**
 * Fires on a specific processing status.
 * 
 * The status can be one of the following: `success`, `error` or `fail`.
 */
do_action( "myplugin/process/status/{$status}" );
do_action( "myplugin/process/status/{$status}/{$action}" );

In this example, you’d have a variable $status and an $action. The first action is triggered when you use it with a certain status, the second action would be triggered if you use a certain status and a certain action. Teak will list these hook variations under the same hook. Because of this, you only need to define a DocBlock for the first hook.

Limitations

This compiler is not a full implementation of phpDocumentor. Rather, it tries to make code documentation that follows the WordPress PHP Documentation Standards more readable, and less techy. Not all official tags are considered yet.

Contributing

Contributions are very welcome.

Roadmap

• CLI: accept a list of files.
• Support nested array arguments
• Add support for Inline Tags.
• Add tests.
• Optimize linking between Markdown documents.