timber / teak
Generate a Markdown reference documentation for PHP projects (optimized for WordPress)
Fund package maintenance!
Open Collective
timber
Requires
- php: >=8.1.0
- phpdocumentor/reflection: ^6.0
- phpdocumentor/reflection-docblock: ^5.3
- symfony/console: ^7
- symfony/filesystem: ^7
README
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
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 eitherfilter
oraction
.--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.