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 ;)

Stay up to date

You can track my blog articles and comments. You may also find my bookmarks interesting. Or Follow me on Twitter