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:
- Sami [example]
- Apigen [example]
- PHP Documentor [example]
- PHP DOX [example]
- PHP Rocco [example]
- Pinocchio [example]
- Doxygen [example]
- and a few others
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.
When you attempt to
composer update you may have issues with phpdocumentor, if so, read next section.
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)
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/kelt/.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.
$ php vendor/bin/apigen generate --source src/ --destination public/apigen
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”
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.
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
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.
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
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:
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.