def246

Today I fiddled around generating docs for a company package. There are a lot of doc generators out there, here are a few and their examples:

I played around with some of these. I like the approach of annotated source code but sometimes it is more useful to have api documentation. Annotated source code is cool because you can follow along line by line and really uncover the guts of a library. When I’m looking for public methods I don’t want to have to sift through annotated source code.

Using composer to install doc generators

"require-dev": {
    "mockery/mockery": "dev-master",
    "phpunit/phpunit": "*",
    "sami/sami": "*",
    "rossriley/phrocco": "dev-master",
    "apigen/apigen": "*"
    "phpdocumentor/phpdocumentor": "2.*",
    "phpdocumentor/template-zend": "*"
},

When you attempt to composer update you may have issues with phpdocumentor, if so, read next section.

PHP Documentor

After running composer update it told me I had to install ext-xml so after running apt-get install php5-xml I attempted another composer update and about 2 minutes into fetching stuff I was presented with this garbage:

- Installing zetacomponents/base (1.9)
Downloading: connection...
Could not fetch https://api.github.com/repos/zetacomponents/Base/zipball/f20df24e8de3e48b6b69b2503f917e457281e687, enter your GitHub credentials to go over the API rate limit
The credentials will be swapped for an OAuth token stored in /home/K.D./.composer/auth.json, your password will not be stored
To revoke access to this token you can visit https://github.com/settings/applications
Username:

Because I didn’t want to give composer my username and password to create an Oauth token, I exited out and told composer to prefer source to get around this issue. Php documentor warns too that there are a lot of dependencies to download so it is likely that I’m just downloading too much. I decided to go a different approach and download the 30 megabyte phar file from http://www.phpdoc.org/phpDocumentor.phar.

After downloading the phar I ran it and it gave the this error:

PHP Fatal error:  Class 'phpDocumentor\Application' not found in phar:///home/K.D./.bin/phar/phpDocumentor.phar/src/phpDocumentor/Bootstrap.php on line 63

So after scouting around some, I found a link on phpDocumentors website that said, “if you have any issues consult: http://silex.sensiolabs.org/doc/phar.html#pitfalls”. After looking at this website the first line states:

Using the Silex phar file is deprecated. You should use Composer instead to install Silex and its dependencies or download one of the archives.

Well… shit, I guess I’m back to the original plan: using composer to install phpDocumentor. So again I attempt composer update and put in my credentials and lo and behold it installs. Now let’s see if this bad boy was worth all the trouble.

vendor/bin/phpdoc -d src/ -t public/phpdocs

The outcome was pretty nice looking. The page is responsive and contained classes. It even had a reports and charts containing things like errors. When you forget place a doc block over a method it produces an error in phpDocumentor, which is pretty cool.

Apigen

$ php vendor/bin/apigen generate --source src/ --destination public/apigen
ApiGen 2.8.0
------------
Scanning /src
[===============================================================>] 100.00%  14MB
Found 207 classes, 0 constants, 0 functions and other 5 used PHP internal classes
Documentation for 207 classes, 0 constants, 0 functions and other 5 used PHP internal classes will be generated
Using template config file /vendor/apigen/apigen/templates/default/config.neon
Generating to directory public/apigen
[>                                                               ]   0.77%  19MB
The class SoftDeletingTrait is in use but has not been found in the defined sources.

Uh oh… it doesn’t know what SoftDeletingTrait is because that is Laravel specific class that is being used in one of my classes. So how to get this thing to work? I started by trying a config file. The SoftDeletingTrait class is in the vendor/ folder so maybe I could exclude that folder but apigen would be smart enough to scan that folder for missing links.

php vendor/bin/apigen generate --source “src,vendor” --destination public/apigen --skip-doc-path=“vendor”

ApiGen 2.8.0
------------
Scanning
 /home/K.D./workspace/lbm/package-devise/src
 /home/K.D./workspace/lbm/package-devise/vendor
[=======>                                                        ]  13.05% 116MB
Used 91% of the current memory limit, please increase the limit to generate the whole documentation.

Crap. Well… I’m off to edit /etc/php5/cli/php.ini and I up the memory limit from 128MB to 1GB. That should be enough right?

memory_limit = 1024M

After running for some a few minutes I still ended up getting the same error.

The class SoftDeletingTrait is in use but has not been found in the defined sources.

So this has all been in vain. Perhaps there is some way to tell apigen to forget about these external classes? The documentation is not very helpful but I do see an --internal flag. That doesn’t help though. After googling some I don’t find any helpful material save one github request that looks related but has been ignored and closed. So I give up on this one - it has far exceeded the 5-10 rule anyway. So Apigen is out.

Sami

This is the same documentor that Taylor uses for Laravel api so it was high on my list of documentors to checkout. I started by creating a configuration file (in my project root) called sami.php:

{% code %} use Sami\Sami; use Symfony\Component\Finder\Finder;

$iterator = Finder::create() ->files() ->name(’*.php’) ->in(DIR . ‘/src’);

return new Sami($iterator, array( ‘title’ => ‘Devise’, ‘build_dir’ => DIR. ‘/public/docs’, ‘cache_dir’ => DIR. ‘/.sami-cache’, ‘default_opened_level’ => 2, )); {% endcode %}

Apparently you can also do themes with Sami. The quickstart docs aren’t clear on themeing but I could create a directory called mytheme and put a manifest.xml in it and then place 'template' => 'mytheme' into the array containing title, build_dir, cache_dir, and default_opened_level. I didn’t need to go into themeing just yet as I’m just testing things out so I just left the theme alone (as default). To run get some documentation I then ran:

vendor/bin/sami.php update sami.php

This produced some really nice looking documentation. A downside to sami is that because it is all contained with an iframe, it is difficult to share links. If you right click on a frame page and open in new tab you can use that link to send to someone, but you loose your cool sidebar (because I’ll say it again… it is an html frame). I didn’t even know we did frames anymore. I haven’t produced one since about two decades ago.

PHP Rocco

I’ve used used docco (node) in the past but in this specific case, annotated source really didn’t provide much value. I wanted to see how easy it was to generate though so I spent the 5 minutes and got it working easily. If we needed annotated source this would be a no-brainer.

phrocco -i src/ -o public/annotated

Using composer to generate your docs

We ended up using but it’s kind of a pain in the ass to remember to type all this stuff. It would be nice if we could just type: make docs. How about the next best thing: composer docs. We can create this script alias using composer:

"scripts": {
  "docs" : "vendor/bin/sami.php update sami.php"
},

Now we’ve got our composer docs and all is well. Not to toot my own horn, but this is a pretty cool setup. Toot toot.

Documentation with PHP