If you've written a PEAR package, it's probably a good idea to submit some end user documentation. Here's how to do it.

How It Works

  • PEAR documentation is stored in XML format in a CVS repository.
  • There's a tool called _phd _that can convert this XML documentation to many formats: HTML, PDF, CHM, etc.
  • The PEAR website periodically checks out the XMLs and uses phd to build all required documentation.
  • The language: 'en' is leading for all other languages. So make your changes there.

So basically you:

  • Save the current documentation
  • Add your own
  • Build & review the documentation locally
  • Submit your addition (with CVS)

In This article..

I'm going to use

  • System_Daemon as example PEAR package.
  • kvz as CVS username
  • kevin as workstation username
  • ~/workspace as project location
  • Ubuntu as Operating system.

So please just substitute these specifics with your own.

1. Prerequisites

Install phd

$ pear install Console_CommandLine
$ pear install Console_Getopt
$ pear channel-discover doc.php.net
$ pear install doc.php.net/phd-beta

I also needed to up my memory limit (I set it to 128M) in /etc/php5/cli/php.ini

Install CVS

In case of Ubuntu:

$ aptitude install cvs

Request Access

If you're planning on maintaining these docs yourself.. You need write-access to the CVS repository.

  • Request CVS karma for peardoc (you'd best ask someone on #PEAR at EFnet IRC)
  • Request CVS access

2. Save Current Documentation

Let's checkout the peardoc folder of the CVS repository

At first you should try to get the pear manual compiled

$ su kevin
$ cd ~/workspace
$ cvs -d :pserver:kvz@cvs.php.net:/repository login peardoc
$ cvs -d :pserver:kvz@cvs.php.net:/repository checkout peardoc
$ cd peardoc

3. Try Building the Docs

Let's just see if everything works:

$ php configure.php
# The command configure.php told you to execute, in my case:
$ phd -L en -f xhtml -t pearchunkedhtml -o build/en -d .manual.xml

If this fails, fix it first.

4. Write Your Own XML Docs

And so in this case the path to store my different chapters as XMLs would be:

en/package/system/system-daemon/*.xml

Also a 'homepage' of your docs can be placed here:

en/package/system/system-daemon.xml

What Should the XML Look Like?

I've just looked at other packages like Console_Table, and used them as example.

5. ReBuild Peardoc

Again, build the docs, and checkout the generated HTML output stored in build/en/html/index.html

You can just point your browser to e.g.: file:///home/kevin/workspace/peardoc/build/ and follow the path to your addition.

Well?

  • Looks good? Goto step 6
  • Looks miserable? Goto step 4

6. Commit Your XML

$ cvs add en/package/system/system-daemon/*.xml
$ cvs add en/package/system/system-daemon.xml
$ cvs commit

7. There Is No Step 7

Thanks to Christian Weiske for holding my hand while I was taking these first steps ; )