https://github.com/timber/teak
https://github.com/timber/teak
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/timber/teak
- Owner: timber
- License: mit
- Created: 2018-03-01T06:11:52.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-10-11T19:53:14.000Z (over 1 year ago)
- Last Synced: 2025-04-03T11:43:51.620Z (about 1 year ago)
- Language: PHP
- Size: 93.8 KB
- Stars: 6
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 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](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/)
- Reference for WordPress action and filters hooks that follow the [Inline Documentation Standards for Actions and Filters](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-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](https://github.com/timber/docs), which uses [Hugo](http://gohugo.io/) as a static site generator.
- [Installation](#installation)
- [CLI Usage](#cli-usage)
- [Generate a class reference](#generate-a-class-reference)
- [Generate a function reference](#generate-a-function-reference)
- [Generate a hook reference](#generate-a-hook-reference)
- [Options](#options)
- [Global CLI options](#global-cli-options)
- [File options](#file-options)
- [Front Matter options](#front-matter-options)
- [DocBlocks](#docblocks)
- [Ignoring Structural Elements](#ignoring-structural-elements)
- [Special Tags](#special-tags)
- [@example](#example)
- [Parameters that are arrays](#parameters-that-are-arrays)
- [Hook Variations](#hook-variations)
- [Limitations](#limitations)
- [Contributing](#contributing)
- [Roadmap](#roadmap)
## Installation
You can install the package with Composer:
```bash
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**
```bash
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**
```bash
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.
```bash
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.
```bash
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
```bash
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](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/). 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.
```php
/**
* 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:
```php
/**
* 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](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-1-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:
```php
/**
* 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](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/) more readable, and less techy. Not all [official tags](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#phpdoc-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](http://docs.phpdoc.org/references/phpdoc/inline-tags/index.html).
- Add tests.
- Optimize linking between Markdown documents.