No longer require system-wide install of phpdoc

[johnkary]

Allows generating documentation without needing phpdoc installed system-wide.

Instead, we can add phpdocumentor/phpdocumentor as a Composer dependency of the bundle, so it will be installed along with the bundle. Now the bundle uses the phpdoc executable installed at ./bin/phpdoc.php

BUT the phpDocumentor2 project is still working through the issues to properly install it via Composer. There is at least 1 bug that must be resolved before this PR can be merged, and also 1 feature request relative to how the developers think the project should be updated we should keep tabs on:

Blocking Bug: phpDocumentor/phpDocumentor#597 - Templates being installed into project root when installed via composer

Relative Feature: phpDocumentor/phpDocumentor#609 - Add command to update phpDocumentor

[artur-gajewski]

johnkary, is this PR still valid? Can I go ahead and merge it?

[johnkary]

I haven't checked for sure, but the linked bug in phpDocumentor2 about the doc templates installed in the wrong location is not yet closed: phpDocumentor/phpDocumentor#597

That bug is slated for their 2.0 final milestone and looks like they're still in alpha.

[artur-gajewski]

@johnkary getting back to this pull request or is teh phpDocument still working on the issue you stated above?

[johnkary]

I played around with this a bit today, and I'm pretty sure I had phpDocumentor working, but only with their dev-develop branch. dev-master had a few issues (one fixed upstream in dev-develop that wasn't back-ported yet) and I'm tired of messing with it for now, but here's what I've found. I feel after this is all setup, it basically makes DocumentorBundle unnecessary.

The following instructions are for dev-master. If you want to use dev-develop there are a few other dependencies you'll need to specify in your composer.json. See the project's packagist.org page

To use phpDocumentor2 with Symfony and install via Composer:

Step 1. Add phpDocumentor2 to your composer.json. If your project uses "minimum-stability": "stable" (which is the default if no value present), you must manually add a few of phpDocumentor's dependencies because the project uses a few unstable (alpha/beta) dependencies and also uses Zend Framework 2 components, which are not hosted through Packagist.org:

{
    "require-dev": {
        "phpunit/phpunit": "3.7.*",
        "artur-gajewski/documentor-bundle": "dev-master",
        "phpdocumentor/phpdocumentor": "dev-master",
        "nikic/php-parser": "dev-master",
        "phpdocumentor/fileset": "1.0.0-beta2",
        "phpdocumentor/graphviz": "1.*@beta",
        "cilex/cilex": "dev-master",
        "cilex/console-service-provider": "1.*@dev",
        "phpdocumentor/reflection-docblock": "2.0.0a1"
    },
    "repositories": [
        { "type":"composer", "url":"http://packages.zendframework.com"}
    ]
}

Step 2. Ensure the following libraries are installed in your dev environment, as phpDocumentor 2 will check for or use them during doc generation:

* XSL extension - `sudo apt-get install php5-xsl`
* GraphViz - `sudo apt-get install graphviz`

Step 3. Allow Composer to resolve your new dependencies:

php composer.phar update

Step 4. Add to .gitignore:

/data
/app/phpdoc.xml

Step 5. Create a file app/phpdoc.dist.xml telling phpdoc some default configuration. We need to tell phpdoc where to find its default responsive template (because it installs in a special location via Composer). But this file can also define the CLI switches you hard-coded in DocumentorBundle's Command class. When using phpdoc.dist.xml this bundle is mostly redundant. For more on phpdoc.dist.xml, see phpdoc's configuration reference documentation for more info:

<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
    <transformations>
        <template name="../data/templates/responsive" />
    </transformations>
    <parser>
        <target>../data/output</target>
    </parser>
    <transformer>
        <target>../data/output</target>
    </transformer>
    <files>
        <directory>../src</directory>
        <ignore>../src/*/*Bundle/Tests</ignore>
        <ignore>../src/*/Bundle/*Bundle/Tests</ignore>
    </files>
</phpdoc>

NOTE: I couldn't get phpDocumentor on dev-master to find the responsive template when using the config file. I could, however, get it to find it when using dev-develop. Maybe specifying it on the CLI with dev-master would work.

Step 6. Add app/phpdoc.xml.dist to your project's version control repository:

git add app/phpdoc.xml.dist

Step 7. Generate your project's documentation:

php vendor/bin/phpdoc.php run -c app/

Step 8. Documentation is output in ./data/output.

I'm curious if this bundle should continue to exist. I suppose if you wanted to provide the easiest way to generate only the basic documentation you could change the bundle to set all CLI flags that are defined by phpdoc.dist.xml above. But I would think most people would need to configure its generation at some point. If hooking phpDocumentor into something like Jenkins I can't see someone wanting to go through the Symfony Console to do so.

[LordBaine2000]

phpDocumentor/phpDocumentor#597 is closed now, might want to consider merging this PR :)