[[PageOutline(2-5,Contents,pullout)]]

= PHPDocumentor plugin for Trac

== Description

This plugin integrates [http://www.phpdoc.org phpdocumentor] documentation into Trac. Started as a simple copy of the DoxygenPlugin.

The phpdoc plugin provides a new main navigation tab (named PHPDoc by default), which will present the phpdoc index page. 

Configuring the PHPDoc plugin should be easy if you have only one PHPDoc generated documentation to wrap, and a bit more involved if you have many, but the goal is to have a great deal of flexibility, in the latter case.

This plugin is tested with Trac 0.11.3.

== Bugs/Feature Requests

Existing bugs and feature requests for PhpdocPlugin are 
[report:9?COMPONENT=PhpdocPlugin here].

If you have any issues, create a 
[/newticket?component=PhpdocPlugin new ticket].

[[TicketQuery(component=WinSvnHooksIntegration&group=type,format=progress)]]

== Download

Download the zipped source from [export:phpdocplugin here].

== Source

You can check out PhpdocPlugin from [/svn/phpdocplugin here] using Subversion, or [source:phpdocplugin browse the source] with Trac.

== Installation

 - Download the zipped source.
 - Extract the zip file
 - Go to the phpdocplugin/0.11 directory and run:
 {{{#!sh
python ./setup.py install
}}}

This will generate a Python egg and copy it into the trac/plugins directory and follow the Configuration steps outlined below.

You may prefer the easy_install way:
{{{#!sh
sudo easy_install https://trac-hacks.org/svn/phpdocplugin/0.11
}}}

You may need to restart your web server to see a PHPDoc button in the navigation tab.

== Configuration

A `[phpdoc]` section should be created in TracIni. 
There is only one mandatory setting, it is the `path` to the generated documentation.
This should match the [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.target -t] parameter of the phpdoc command. If that is a relative path, you'll need to prepend the current working directory used when running `phpdoc`.

Also, don't forget to grant the users the PHPDOC_VIEW permission, or you'll just get a blank page.

Note that there's also the [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.output -o] parameter which might play a role here. I got best results with the value 'HTML:Smarty:PHP'.

== Example

First checkout the latest version of your trunk:
{{{#!sh
mkdir/var/cache/phpdoc
cd /var/cache/phpdoc
mkdir myproject
cd myproject
svn co http://my.svn.server.org/svn/myproject/trunk source
mkdir doc
/path/to/installed/phpdoc -o HTML:Smarty:PHP -d source -t doc
}}}

Now you should have the latest source in `/var/cache/phpdoc/myproject/source` and the generated documentation in `/var/cache/phpdoc/myproject/doc`.

Now setup Trac's configuration:
{{{#!ini
[phpdoc]
path = /var/cache/phpdoc/myproject/doc
}}}

The next time, you only need to run "svn up" instead of "svn co" and run phpdoc again with the same parameters.

It's possible all other options (configuration options multiple documentation projects, links in wiki) will work also, just like the ones specified with DoxygenPlugin, but there are no guarantees.
On a first view, it appears to work good enough for me with this source and configuration.

'''Note''': If you install the plugin globally, you'll also need to enable it in `trac.ini` as follows:
{{{#!ini
[components]
phpdoctrac.* = enabled
}}}

== TracLinks

It's possible to create links to phpdoc documentation from anywhere within a Wiki text, by using the `phpdoc:` link prefix.

The general syntax of such links is: `phpdoc:documentation_file`.

Some examples:
{{{
[phpdoc:index.html Documentation] # Simple documentation in phpdoc path.

[phpdoc:Database/db.html Class db from Package Database] @ Link to a class in a Package
}}}

== Recent Changes

[[ChangeLog(phpdocplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:exarv] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''