Documentation for PHP
Ever have an issue with PHP documentation and file a bug, only to have it sit for a long time? Or find a typo or other error in the documentation and have someone tell you "send me a patch". PHP has, in my opinion, some of the best API documentation around. But the documentation is written, edited, and updated completely by volunteers so it's only as good as the people who help write it. And there are never, ever enough people who want to document an open source project.
Ever contemplate contributing back to PHP? Have you ever thought about submitting a change for the documentation, but couldn't figure out where to start? Documentation is an easy way to give something back to the PHP community. Yes I said easy - I'm not lying. There just isn't good documentation on how PHP documentation works. (PHP doesn't have enough volunteers to keep up with API documentation, much less people to spare to document the documentation system)
PHP documentation is written in a slightly modified Docbook 5 format. The files are all available in PHP CVS. Just to confuse the world, PHP documentation is often referred to as phpdoc - which is not phpdoc or phpdocumentor. Those are scripts for generating documentation from comments in php scripts. The phpdoc at php.net is for documenting the PHP runtime, API, and extensions.
If you open one of the xml files in php cvs you'll see it doesn't look very much like the documentation on the PHP website. The information in those files is "rendered" with a system written in PHP. I think it's rather cool that PHP documentation is created with PHP. The documentation is written in XML because the data can be output into various formats, from straight html to chm. The renderer that PHP uses is called PhD (that's PHP-based DocBook Renderer, someone was trying to be clever) The renderer does not support every DocBook 5 tag yet and PHP has added additional tags to the DTD . All the extensions live in their own XML namespace "phd:" which resolves to http://www.php.net/ns/phd.
So, you've decided you want to help out - where do you start? Before you can edit a file or document an extension you need to be able to build the manual to check your changes. So you need a working install of PhD. In order to accomplish this goal you'll need three things installed and configured, which is what this article is intended to help with.
- PHP installed somewhere on your system. If you're using Windows you MUST use PHP 5.3 (for getopt support) or have 5.2.x + PEAR + PHP_Compat installed.
- The phpdoc xml files from cvs
If you already know your way around an operating system there's a "five minute install" version you can jump to, otherwise keep reading for the "long view".
I'll be showing you how to do this on windows, since most people using linux, mac or a unix variant know what they're doing, but most of the steps are similar for any operating system.
If you're not on windows, chances are you have PHP installed somewhere, and your getopt support works fine - move along.
If you ARE on windows you will need PHP 5.3 to run PhD, or a PEAR install with PEAR's PHP_Compat package available. But that would take too long, and I'm lazy (besides, it's fun to play with development PHP versions)
It is VERY easy to install multiple versions of PHP on the same machine, so I'll introduce you to my famous "three file install" (That's right, you only need three files to run PHP on windows)
First of all, pick a spot for your new 5.3 install. I'm boring, I'm putting mine into c:\\build\\phd\\php. Make a directory for it wherever you decide to put it. Next you need PHP 5.3 Notice this is NOT a released version and may have quirks. Since we'll be using the CLI version of PHP, you can get the NTS variety. NTS stands for non-thread safe. You also have a choice of which compiler version to use - VC6 or VC9. What's the difference? VC9 is faster, better, more interesting - but you'll need to run a little msi installer for a runtime .dll the first time you install PHP. The VC6 version is slower but no installer required.
QA builds of PHP 5.3 can be found at windows.php.net Download either the VC6 non thread safe version or the VC9 non thread safe version of the PHP 5.3 beta1 . If you're very brave (or insane, or any combination thereof) you can try a snapshot version of 5.3 available from the same site.
Open up the zip file and grab three things - php.exe, php5.dll, and php-ini.recommended and put it in the location you've chosen (c:\\build\\phd\\php for me). Rename php-ini.recommended to php.ini If you're using the VC9 build for the first time, you'll need to install the Microsoft 2008 C++ runtime as well.
One last thing - PHP 5.3 is VERY noisy if you don't set a default timezone! Open up that php.ini file (even notepad will work for this) and find the line that says
Remove the semi-colon (that's a comment) and set it to ... something. You can find a list of timezones at php.net/timezone (man I love the docs... and soon you can help make them even cooler) My new line looks like this
date.timezone = America/Detroit
Want to test your new PHP install? Open a command window (you can type cmd.exe into the run dialog from the start menu). Then cd to the location of your new PHP and type php -v. You should get information about your new php install.
A little note, you'll be doing a lot of command line work for PhD so you'll need to be properly acquainted with cmd.exe.
If you're on XP the Open Command Window Here PowerToy will make your life SOO much easier. Simply install it, and then right click on any directory. The context menu will have an "Open Command Window Here" choice.
If you're on Vista - just hold the shift key while right clicking on a directory and the "Open Command Window Here" choice will appear. But on Vista dragging and dropping files into cmd.exe to get the full path is broken - you can get a magic "Copy as Path" choice if you hold shift when right clicking on a file. So on XP you can drag a file into a command window and get a magic path - on Vista you have to shift and right click until your fingers bleed.
There are two basic ways to install PhD. One way uses the PEAR installer, but I haven't had good luck with it and local PEAR installs (and I am NOT wanting a global install on this machine - and yes Helgi I should file a bug ... not enough time in my day).
If you have a working PEAR installer on your system ...
pear channel-discover doc.php.net
pear install doc.php.net/phd-beta
You only need to do the channel-discover call once, after that your PEAR installer will know where to find PhD. Future versions of the PEAR installer will probably have the channel already available for you, but for now you need to "discover" it first.
If you're lazy, or PEAR is flaky on your system, or you're just a contrary person it is easy to install PhD by hand. First you need the source, the current "release" is found at http://doc.php.net/phd/PhD-0.4.5.tgz. Unpack it into any location you please. I keep all my current work in c:\build, so I'll be putting it at c:\\build\\phd for this article. If you don't have a program capable of dealing with .tgz files on windows, 7-zip is a great open-source choice (even works on 64 bit correctly).
You will need to do one more step after extracting the files. The PEAR installer would have changed information in some files for you, since it didn't, you need change one file by hand.
First of all, open phd.bat. Do NOT open it in notepad.exe - why? Because the line endings are wrong (again, I need to file a bug...) Instead open it with wordpad.exe or your favorite editor (Komodo/KomodoEdit works great - yes I am pimping my favorite editor) You can't just right click on on the file either, you'll need to open wordpad (or your editor) and open the file from there. (Notice if you open the file in wordpad, you need to change the file type filter to have the .bat show up).
This is what you should see in the file
REM $Id: phd.bat,v 184.108.40.206.2.1 2008/12/02 21:27:59 kalle Exp $
@"@php_bin@" "@bin_dir@\\build.php" %*
You need to change two things - the @php_bin@ should be the path to your newly placed 5.3 php.exe, mine is at C:\\build\\phd\\php\\php.exe - notice if you have spaces in your path, be sure to keep the quotation marks in the file intact. The other thing you need to replace is @bin_dir@ - which should be the path to where you have placed the phd files - in my case c:\\build\\phd
My finished version is
REM $Id: phd.bat,v 220.127.116.11.2.1 2008/12/02 21:27:59 kalle Exp $
@"C:\\build\\phd\\php\\php.exe" "c:\\build\\phd\\build.php" %*
There - was that so hard?
Now it is finally time to get the php documentation sources. If you're not on windows, or are addicted to the command line and already have CVS set up somewhere, the relevant commands to get a phpdoc checkout are
cvs -d:pserver:email@example.com/repository login
cvs -d:pserver:firstname.lastname@example.org/repository co phpdoc
The password is "phpfi"
But if you prefer something a little easier to work with...
The single easiest way to do any kind of cvs on Windows without losing your mind is tortoisecvs. Seriously, if you do not have it, get it. It even does tricky stuff like translating your line endings to the nix version so nix people don't jump down your throat after a commit. You can use command line or other versions of cvs clients, but I'm going to explain how to do the checkout with tortoisecvs. Also make sure you have a CURRENT version of tortoisecvs - there were some nasty pserver login bugs with earlier versions. And make sure you restart after installing or upgrading - theoretically you don't have to but this IS windows after all. If you're installing tortoisecvs and the cvsnt installer portion confuses you, remember you ONLY need the client stuff, not the server or anything else ;)
Pick a spot to dump the phpdoc files. Again, I'm so terribly original so I'm going to be using c:\\build\\phd\\phpdoc . Go to the directory ABOVE where you want phpdoc located (for me this is c:\build\phd) and right click. See the pretty tortoisecvs stuff that appears? Choose "Cvs Checkout" and get a pretty dialog. First of all copy this line
And paste it into the top line there where it says CVSROOT (see how the other stuff magically fills in?)
Next where tortoisecvs says "module" put phpdoc
Tortoisecvs will automatically put the checkout in a folder called "phpdoc" - if you want a different name, hit the options tab, hit the "Enter your own folder name" option and put the name you want in the dialog. Now for the fun - click OK!
Now - tortoisecvs might pop up a login window, or it might not - if it DOES the password is "phpfi"
Watch the pretty checkout scroll by - warning - this is is big and will take a bit of time. Finally you'll see the "Success, CVS operation completed" message.
Look in the newly created phpdoc directory and you should have a TON of files in there ;)
One more step - we need to build a special file called .manual.xml using PHP. Here you're going to get a quick lesson in file paths. You need to use your PHP 5.3 php.exe to run the configure.php file in your new phpdoc directory. Below is what I typed, the location of your php.exe might be different. If you're on XP you can simply drag and drop php.exe onto a command window to get the full path. Vista you need to shift, right click, choose "Copy as Path", right click in your command window, choose paste.
Pain... In... Rear.... (or just type out the full path if you're bored)
"c:\\build\\phd\\php\\php.exe" configure.php --with-php="c:\\build\\phd\\php\\php.exe"
Notice that you'll need to tell configure.php what php executable to use for it's magic, and it is generally a good idea to quote paths on windows because you never know when a space might pop up.
You should see a little message that says "all good, done" - congratulations! You have a .manual.xml file.
Take your phd.bat file and copy it into your phpdoc checkout (really, will make your life easier)
Now you have all the necessary ingredients to build the docs - the cvs checkout, PhD, a PHP CLI install with getopt support. Time to finally build some documentation.
Open a command window and cd to where you have that phpdoc checkout located. If you followed my advice earlier you can just right click on your the directory and tell windows to "open command window here". Running the following code
to get some extremely ugly help output (it's longer than 80 characters, I know, I know, another bug to file)
You can read the explanations to get exactly the command you need. But I'll save you some time and energy. If you're just looking to build one version of the docs so you can track your changes, the command you're looking for is
phd -d .manual.xml -f xhtml -t chunkedhtml
This will create a directory called "html" with a plain (as in no css) rendering of the PHP docs.
I'd like to create an html version with php.net style css - but again, something to add to a bug report (preferably with a patch)
Here's the short version wrapup of installing PhD - if you've read the long version this is just review
- Get a working PHP install.
- On windows, install PHP 5.3, or PEAR with PHP_Compat package
- On other systems, any PHP above 5.2 will work
- Install PhD
- Using Pear
pear channel-discover doc.php.net pear install doc.php.net/phd-beta
- By hand
Download PhD-0.4.5.tgz and decompress it somewhere
Change @php_bin@ location in phd.bat on windows or the shebang at the top of the build.php file to the absolute path to your PHP CLI binary. If on windows changed the @bin_dir@ in phd.bat to your phd directory
- Using Pear
- Get phpdoc sources
cvs -d:pserver:email@example.com/repository login cvs -d:pserver:firstname.lastname@example.org/repository co phpdocPassword is phpfi
- Run configure.php in your phpdoc checkout
php configure.phpWindows users will need to add ---with-php="full/path/to/php.exe"
- Run PhD
From inside your phpdoc checkout run
phd -d .manual.xml -f xhtml -t chunkedhtml
Onward to Fame
Now you can build the PHP documentation any time you want. So what comes next? Probably editing the existing xml and creating patches. But that's a post for another day. You can find more information about phpdoc and phd from the Documentation Wiki and the phpdoc volunteers hang out on efnet on #php.doc