Rendering the manual
The PEAR documentation gets - like the PHP Manual - built using PHP's very own DocBook rendering system called PhD. Installation is a breeze using pear:
$ pear install doc.php.net/phd-beta doc.php.net/phd_pear-beta
...
$ phd --version
PhD version: phd-from-cvs
Copyright (c) 2007-2009 The PHP Documentation Group
When using PEAR before verson 1.8.0, you need to discover the channel first.
Besides that, one only needs a SVN checkout of the peardoc module.
Preparing the build
Before building, you need to use the
configure.php script provided by
peardoc. This script serves two purposes:
-
Validate XML
-
Combine all xml files into one large single file to speed up the build process
Just change into your peardoc source folder
and run:
$ php configure.php
Generating chapters.ent for en
3376 xml files
6 php example files
done
Loading manual into one giant file
Validating done
Now call phd: phd -L en -P PEAR -f xhtml -o build/en -d .manual.xml
If you see those lines, everything is fine and you can continue compiling the manual.
Like with every proper unix tool, you can use php configure.php --help to get an overview about the supported command line parameters.
In case something goes wrong, the config script will tell you either where it failed, or which commands to execute to find the right spot:
$ php configure.php
Generating chapters.ent for en
3376 xml files
6 php example files
done
Loading manual into one giant file
There were warnings loading the manual Warning:
DOMDocument::load(): Opening and ending tag mismatch:
set line 46 and book in
/home/cweiske/Dev/cvs/pear/peardoc/manual.xml, line: 67 in
/home/cweiske/Dev/cvs/pear/peardoc/configure.php on line 278
....
Exception: Failed to load manual.xml
Fix the error and run configure.php again
until it tells you everything is ok.
Compiling the manual
Now that you configured everything properly, run the command that
configure.php told you. The command will be
something along that:
$ phd -L en -P PEAR -f xhtml -o build/en/ -d .manual.xml
configure.phpgenerated a giant manual file named.manual.xml. If you use plainmanual.xmlyour build will take about double as long as with.manual.xml(note the leading dot).
When PhD doesn't report any errors, your generated HTML
documentation will be available in
build/en/html/.
Partial builds
When writing documentation for a single package, you probably
don't always want to compile the whole manual. PhD allows you to
compile a small part of the manual which is faster than doing the
whole thing. Just pass "-p
package.category.packagename" as parameter to PhD, and only
the part of the manual below that ID will be created.
At the time of writing, partial rendering in PhD is not noticable faster than creating the whole manual. This will change in the future, though.
In case you didn't change the structure (adding or removing IDs), you can skip PhD index creation (
-I) which will save you about 15-20 seconds build time.
Other sources to test your documentation
Several PEAR members regularly build the documentation on their own machine in shorter cycles than the pear.php.net server. When you don't have the chance to test and build your changes, you can use any of this build servers to check everything is fine:
| PEAR member | Build interval | Format | Build log |
|---|---|---|---|
| Brett Bieber | 2 hours | Chunked HTML | log |
| Benedikt Hallinger | at 06:00 and 18:00 CEST | Chunked HTML | log |