grunt-phpdocumentor

Runs the PHPDocumentor documentation generator tool.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
grunt-phpdocumentor
1980.4.110 years ago11 years agoMinified + gzip package size for grunt-phpdocumentor in KB

Readme

grunt-phpdocumentor
Runs the PHPDocumentor documentation generator tool.
Built with Grunt This build include phpDocumentor version 2.2.0, other versions can be specified by the phar option This plugin runs the command : ``phpdoc -d dir -t target``.

Getting Started

This plugin requires Grunt ~0.4.1 If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command: ```shell npm install grunt-phpdocumentor --save-dev ``` One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript: ```js grunt.loadNpmTasks('grunt-phpdocumentor'); ```

The "phpdocumentor" task

Overview

In your project's Gruntfile, add a section named phpdocumentor to the data object passed into grunt.initConfig(). ```js grunt.initConfig({
phpdocumentor: {
dist: {
options: {
directory : './',
target : 'docs'
}
}
}
}) ``` You can also use many Grunt targets if you have several phpDocumentor documentations to generate. ```js grunt.initConfig({
phpdocumentor: {
// Place here Task level options (i.e common to all your phpDocumentor targets)
options : {
command : 'run',
},
// Grunt Target used to generate a first documentation
first_api_documentation : {
options: {
directory : 'src/first_api',
target : 'docs/first_api_documentation'
}
},
// Grunt target used to generate a second documentation
second_api_documentation : {
options : {
directory : 'src/second_api',
target : 'docs/second_api_documentation'
}
},
// Sample target used to display the phpDocumentor help
display_help : {
options : {
command : 'help'
}
}
}
}) ```

Options

options.bin( optional )

Type: String Default value: phpdoc Path to the phpdoc executable, by default it will use the one that come with task. It is located on the bin folder. WARNING : We kept this option documented here only for versions 0.1.0 and 0.3.0 of the plugin. This option has been removed in version 0.4.0 because it was not portable across operating systems.

options.command ( optional )

Type : String Default value: run The name of the phpDocumentor command to execute, the following phpDocumentor commands are available in phpDocumentor : help : Displays help for a command list : Lists commands parse : Creates a structure file from your source code run : Parses and transforms the given files to a specified location transform : Converts the PHPDocumentor structure file to documentation project:parse : Creates a structure file from your source code project:run : Parses and transforms the given files to a specified location project:transform : Converts the PHPDocumentor structure file to documentation template:list : Displays a listing of all available templates in phpDocumentor WARNING : All the phpDocumentor commands can be called using the plugin, but for now you can only use the phpDocumentor [-t|--target[="..."]] and [-d|--directory[="..."]] command line options which are not sufficient to make the transform and project:transform correctly work.

options.directory( optional )

Type: String Default value: ./ Comma-separated list of directories to (recursively) parse (multiple values allowed). It will default to the folder where Gruntfile is located.

options.phar( optional )

Type: String Default value: undefined This option is not integrated in phpDocumentor tool and is specific to the plugin. The purpose of this option is to allow you to provide a path to a custom phpDocumentor PHAR file or to indicate to the plugin to use the phpdoc command available in your system. If this option is not specified then the plugin will automatically use the integrated phpDocumentor PHAR file. If you want to provide a path to a custom PHAR file you can provide it as a string : ```js grunt.initConfig({ phpdocumentor: {
dist: {
phar : 'documentation_tools/phpDocumentor.phar'
}             
}, }) ``` If you want to use the phpdoc command which is available on you system instead then you can the null value to the phar option : ```js grunt.initConfig({ phpdocumentor: {
dist: {
phar : null
}             
}, }) ```

options.target( optional )

Type: String Default value: docs Path where to store the generated output. It will default to a folder named 'docs'

Usage Examples

``grunt phpdocumentor``

Release History

0.4.1

Fix a documentation problem, the options object was not used in the configuration sample. Document the use of the command option Describe how to use the plugin with Task Level options Describe how to use the plugin with multiple phpdocumentor targets Implement unit tests to run all the phpDocumentor commands (except the transform and project:transform commands

0.4.0

BREAKING CHANGE, WARNING: The bin option has been deleted and replaced by the phar option, if null is passed to the phar option then the plugin uses the phpdoc command available, if the phar option is undefined then the plugin uses the packaged phpDocumentor PHAR, if the phar option is not null and not undefined then it express a path to a phpDocumentor PHAR file on the file system Add more robust unit tests The unit tests are executed on the develop branch with the GoMoob continuous integration server each time the source code is updated on this branch Now the plugin inspects the [Exception] string in the phpDocumentor output to know if a phpDocumentor exception has been encountered and make the Grunt task fail Add the build with grunt badge to the README.MD file Global documentation improvements Add lot of comments in the plugin code The bin\phpdoc bash script has been deleted because bash is not installed on all UNIX platforms and because using a bash script is not portable across platforms Upgrade the phpDocumentor PHAR to version 2.2.0 of phpDocumentor Remove the use of the loadash _.extend() function and replace it with the standard Grunt task.options() function Now the plugin checks if PHP CLI is available at command line Global refactorings Begin to support the execution of the help, parse, project:parse, transform, project:transform, list,
`template:list` commands

0.3.0

Including ``phpDocumentor version 2.0.0a12`` on the bin, giving default to all options

0.1.0

First release