{"id":18509134,"url":"https://github.com/timber/teak","last_synced_at":"2025-04-09T03:32:23.822Z","repository":{"id":56223269,"uuid":"123390791","full_name":"timber/teak","owner":"timber","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-11T19:53:14.000Z","size":96,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T11:43:51.620Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timber.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"timber","github":"timber"}},"created_at":"2018-03-01T06:11:52.000Z","updated_at":"2024-10-11T19:52:01.000Z","dependencies_parsed_at":"2024-09-13T17:22:35.017Z","dependency_job_id":"e67270a4-5add-45a4-ae18-275cd57358cb","html_url":"https://github.com/timber/teak","commit_stats":{"total_commits":50,"total_committers":2,"mean_commits":25.0,"dds":"0.020000000000000018","last_synced_commit":"a5af1504cadb8e5d2277069165caf948d1d0c012"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timber%2Fteak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timber%2Fteak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timber%2Fteak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timber%2Fteak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timber","download_url":"https://codeload.github.com/timber/teak/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247973947,"owners_count":21026738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T15:16:34.993Z","updated_at":"2025-04-09T03:32:23.565Z","avatar_url":"https://github.com/timber.png","language":"PHP","funding_links":["https://opencollective.com/timber","https://github.com/sponsors/timber"],"categories":[],"sub_categories":[],"readme":"# Teak\n\nTeak is a CLI utility to generate a Markdown reference documentation for PHP projects (optimized for WordPress).\n\nIt can generate documentation for\n\n- 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/)\n- 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).\n\nYou can use documentation generated by Teak to create a documentation website when you use it in combination with a static site generator.\n\nTeak is used to generate the [documentation for Timber](https://github.com/timber/docs), which uses [Hugo](http://gohugo.io/) as a static site generator.\n\n\u003c!-- TOC --\u003e\n\n- [Installation](#installation)\n- [CLI Usage](#cli-usage)\n    - [Generate a class reference](#generate-a-class-reference)\n    - [Generate a function reference](#generate-a-function-reference)\n    - [Generate a hook reference](#generate-a-hook-reference)\n        - [Options](#options)\n    - [Global CLI options](#global-cli-options)\n        - [File options](#file-options)\n        - [Front Matter options](#front-matter-options)\n- [DocBlocks](#docblocks)\n    - [Ignoring Structural Elements](#ignoring-structural-elements)\n    - [Special Tags](#special-tags)\n        - [@example](#example)\n        - [Parameters that are arrays](#parameters-that-are-arrays)\n    - [Hook Variations](#hook-variations)\n- [Limitations](#limitations)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n\n\u003c!-- /TOC --\u003e\n\n## Installation\n\nYou can install the package with Composer:\n\n```bash\ncomposer require timber/teak --dev\n```\n\n## CLI Usage\n\n### Generate a class reference\n\nWhen you pass a folder to the Class Reference Generator, it will generate a separate Markdown file for each class that it finds.\n\n**Use a folder as the input**\n\n```bash\nvendor/bin/teak generate:class-reference ./lib/ --output ./docs/reference\n```\n\nThis searches all the PHP classes in `./lib/` and outputs the Markdown files into `./docs/reference`.\n\n**Use a single file as the input**\n\n```bash\nvendor/bin/teak generate:class-reference ./lib/Post.php --output ./docs/reference\n```\n\n### Generate a function reference\n\nThe Function Reference Generator will search all the files for global functions and output them in a single Markdown file. \n\n```bash\nvendor/bin/teak generate:function-reference ./lib/ --output ./docs/\n```\n\n### Generate a hook reference\n\nThe Hook Reference Generator will search all the files for WordPress actions or filters and outputs one single Markdown file, with all the hooks found.\n\n```bash\nvendor/bin/teak generate:hook-reference ./lib --output ./docs/hooks --hook_type=filter\nvendor/bin/teak generate:hook-reference ./lib --output ./docs/hooks --hook_type=action\n```\n\n#### Options\n\n- `--hook_type` – The hook type to look for. Has to be either `filter` or `action`.\n- `--hook_prefix` – Hook prefix (to select only hooks with a certain prefix).\n\n### Global CLI options\n\nDisplay help for commands\n\n```bash\nvendor/bin/teak generate:class-reference -h\nvendor/bin/teak generate:function-reference -h\nvendor/bin/teak generate:hook-reference -h\n```\n\n#### File options\n\n- `--file_name` – File Name (the .md extension is appended automatically)\n- `--file_prefix` - File Prefix\n- `--file_title` - File Title (Heading 1 in the Markdown document). Only applicable to hooks and functions reference.\n\n#### Front Matter options\n\nTeak 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.\n\n- `--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).\n\n## DocBlocks\n\nTeak 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.\n\n### Ignoring Structural Elements\n\nAn element (class, method, property) is **ignored when one of the following conditions** applies:\n\n- No DocBlock is provided\n- No `@api` tag is present\n- An `@ignore` tag is present\n- An `@internal` tag is present\n- The visibility is `private` (applies to methods only)\n\nThis means that for Markdown files to be generated for a class at all, you’ll need at least a DocBlock, with an `@api` tag.\n\n```php\n/**\n * Class My_Public_Class\n *\n * @api\n */\nclass My_Public_Class {}\n```\n\n### Special Tags\n\n#### @example\n\nThe `@example` tag allows you add code examples to your DocBlocks, including fenced code blocks:\n\n```php\n/**\n * Function summary.\n * \n * Function description.\n *\n * @api\n * @example\n *\n * Optional text to describe the example\n * \n * ```php\n * my_method( 'example', false );\n * ```\n *\n * @param string $param1 Description. Default 'value'.\n * @param bool   $param2 Description. Default true.\n */\nfunction my_method( $param1 = 'value', $param2 = true ) {}\n```\n\n#### Parameters that are arrays\n\nTeak supports [parameters that are arrays](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-1-parameters-that-are-arrays).\n\n### Hook Variations\n\nSometimes 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:\n\n```php\n/**\n * Fires on a specific processing status.\n * \n * The status can be one of the following: `success`, `error` or `fail`.\n */\ndo_action( \"myplugin/process/status/{$status}\" );\ndo_action( \"myplugin/process/status/{$status}/{$action}\" );\n```\n\nIn 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.\n\n## Limitations\n\nThis 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.\n\n## Contributing\n\nContributions are very welcome.\n\n## Roadmap\n\n- CLI: accept a list of files.\n- Support nested array arguments\n- Add support for [Inline Tags](http://docs.phpdoc.org/references/phpdoc/inline-tags/index.html).\n- Add tests.\n- Optimize linking between Markdown documents.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimber%2Fteak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimber%2Fteak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimber%2Fteak/lists"}