phpDocumentor Tutorial

This tutorial describes, in a detailed step-by-step manner, what you need to do to install and configure the phpDocumentor package so that you can generate a local copy of the Joomla! documentation using the official Joomla! repositories. It has been written primarily for the benefit of newcomers to the Joomla! Documentation Team so that they can begin to make their own amendments to the documentation and test them on a local system before committing changes to the repository. However, others may find it useful too; for example, someone who wants to generate local documentation in formats that are not officially supported or in a customised format.

Please report any errors or omissions in this tutorial on the Joomla! Developer Documentation Forum

Aims

To understand how Joomla! documentation is produced and be confident in being able to test and commit changes to the official Joomla! documentation repository.

Objectives

On completing this tutorial you should be able to:

• install and configure the phpDocumentor package
• obtain local working copies of the Joomla! documentation repository and the Joomla! code repository
• understand the structure of the documentation repository
• run phpDocumentor to generate local copies of the documentation in a variety of formats
• TODO: edit the documentation and test the changes produced
• TODO: commit changes to the documentation repository
• TODO: understand the release cycle for Joomla! and its associated documentation

Before you start

Below is a list of the things you will need in order to complete this tutorial.

• an Apache web server capable of running PHP scripts
• PHP version 4.x (there is a warning in the phpDocumentor documentation that the PDF Convertor will not work in PHP5)
• a Subversion (SVN) client (suitable clients and where to obtain them are listed in the tutorial)
• internet access
• a web browser
• a username/password for access to forge.joomla.org (TODO: CHECK, IS THIS TRUE?)
• commit access to the documentation repository (if you wish to commit changes)

Introduction to Joomla! documentation

The Joomla! source code has, from the very early days, included a liberal sprinkling of comments and tags placed there so that the phpDocumentor package could automatically generate a limited form of documentation. At first this was intended for use only by developers and prior to Joomla! 1.1 it was of limited use even to them! However, with the advent of Joomla! 1.1 a concerted effort was made to improve the quality of the phpDocumentor output and indeed this tutorial is part of that effort.

From Joomla! 1.1 onwards most, if not all, developer documentation will be held in DocBook XML format in a Subversion (SVN) repository. There are several reasons for this choice:

• the source documents are held in a version control system (Subversion) so all changes are tracked and any mistakes can be quickly "rolled back"
• it is much easier to generate documentation in a variety of formats, such as HTML, CHM (Windows help file format) and PDF
• it is possible for anyone to take the source documents and "repurpose" them into any format they choose

In brief, the Joomla! source code is held in an SVN repository and contains special "DocBlocks" which provide additional information about what each piece of code is doing. The phpDocumentor package scans through this source code and analyses the code itself, together with the information in these DocBlocks and uses that data to generate documentation. This is often referred to as API (for Application Programming Interface) documentation and it's really only useful to software developers.

To increase the usefulness of the documentation, additional information is gathered into "tutorials", written in DocBook XML, which are also scanned and analysed by phpDocumentor and incorporated into the final documentation. This additional information is also primarily of use to developers, but it is not restricted to that audience and there is no technical reason why we should not include other forms of documentation too.

These DocBook source documents are also held in a Subversion repository, but for organisational reasons it is not the same repository as the Joomla! source code itself. So, to generate local copies of the documentation you will need to download the Joomla! source code from its' repository and the Joomla! documentation source from its' repository and merge the two together before getting phpDocumentor to work its magic.

Note for Microsoft Windows users: You will see references to ownership/permissions issues throughout this tutorial. These are not relevant on some versions of the Windows platform and you can safely ignore them.

Now let's proceed with the tutorial...

Step 1: Download and install phpDocumentor

You need to obtain a copy of phpDocumentor. At the time of writing the current version of phpDocumentor is 1.3.0 RC4 and can be downloaded from here. The phpDocumentor project has a website at www.phpdoc.org where further information may be found if required.

Change your current working directory to the Apache web document root (this might, for example, be '/var/www/html'). Create a new sub-directory where you can extract the phpDocumentor package to; let's call it 'phpdoc'. You may very well need to be logged in as the root user to do this. Extract the phpDocumentor download file into this new directory. On a Linux box you might do something like the following:

cd /var/www/html
mkdir phpdoc
cd phpdoc
tar xvfz /home/chrisd/PhpDocumentor-1.3.0RC4.tar.gz
 

Once the extraction is completed you will notice that you have the following directory structure:

/var/www/html
+- phpdoc
   +- package.xml
   +- PhpDocumentor-1.3.0RC4
      +- phpDocumentor
      +- user
      +- and many others...
 

You also need to create a new directory somewhere under the Apache document root, to hold the output documents generated by phpDocumentor. Let's call this directory 'joomla11'. You will probably need to change the permissions on this directory to allow Apache write-access to it. On a Linux box this might look like this:

cd /var/www/html
mkdir joomla11
chown apache.apache joomla11
 

[root@molybdenum root]$ cd /var/www/html
[root@molybdenum html]$ grep ^User /etc/httpd/conf/httpd.conf
User apache
[root@molybdenum html]$ grep ^Group /etc/httpd/conf/httpd.conf
Group apache
[root@molybdenum html]$ chown apache.apache joomla11
 

If you are running Apache 2.x then it's slightly different:

root@palladium root:~$ cd /var/www/html
root@palladium html:~$ grep ^User /etc/apache2/apache2.conf
User www-data
root@palladium html:~$ grep ^Group /etc/apache2/apache2.conf
Group www-data
root@palladium html:~$ chown www-data.www-data joomla11
 

Note that you may very well need to log in as the root user to do this.

Step 2: Get a working copy of the Joomla! documentation

The Joomla! documentation is held in a Subversion (SVN) repository and you will therefore need an SVN client in order to checkout a local working copy of the documentation from the repository. Graphical SVN clients are a bit thin on the ground at the moment but the following clients (graphical and command-line) are known to work:

• RapidSVN for Linux and all versions of Microsoft Windows (including 95/98/98SE)
• TortoiseSVN for later versions of Microsoft Windows only
• Command-line packages for most platforms including RedHat, Fedora Core, Debian, SuSE, {Net, Free, Open}BSD, Solaris, Mac OS X, most versions of Windows and IBM OS/400

Checkout a working copy of the Joomla! Documentation repository from http://joomlacode.org/svn/joomla/documentation/trunk. On my system I put this into a directory called '/home/chrisd/joomladoc'. Once checked out from the repository, the layout of this directory should be as follows:

/home/chrisd/joomladoc
+- branches
+- phpdoc
   +- phpDocumentor
      +- Convertors
         +- CHM
         +- HTML
   +- user
+- tags
+- trunk
+- tutorials
 

The structure of the 'phpdoc' directory mirrors that of the phpDocumentor package that we extracted into the Apache document root. phpDocumentor uses what it calls 'convertors' to make different forms of output documentation. In the Convertors/CHM and Convertors/HTML directories you will find Joomla! versions of the CHM default convertor and the HTML:Frames:DOM:earthli covertors respectively. The CHM convertor generates Microsoft Windows HTML Help files and at the present time has not been specifically customised for Joomla! The HTML convertor generates the output that we are already familiar with on api.joomla.org.

Step 3: Get a working copy of the Joomla! code

The Joomla! code itself is also held in a Subversion (SVN) repository and you will need to download a local working copy of that too. The latest (development, unstable) version of Joomla! is held in the trunk directory of the Joomla! repository which is at http://joomlacode.org/svn/joomla/development/trunk. On my system I put this into a directory called 'home/chrisd/joomla-svn'.

Step 4: Configure phpDocumentor

Copy the convertors from the SVN working copy of the Joomla! documentation into the equivalent directories in the phpDocumentor package in the webserver document root. On Linux this might look like this:

cd /var/www/html/phpdoc/PhpDocumentor-1.3.0RC4
cp -r /home/chrisd/joomladoc/phpdoc/* .
 

By copying the 'phpdoc' directory from the Joomla! documentation repository to the phpDocumentor installation directory, you will have installed the Joomla!-specific convertors (we will explain that a little later). For each phpDocumentor convertor that you want to use you will need to ensure that Apache has write access to the Smarty template directory within each such convertor directory. The directory to look out for is called 'templates_c'. Example:

cd /var/www/html/phpdoc/PhpDocumentor-1.3.0RC4
chown apache.apache phpDocumentor/Converters/HTML/frames/templates/DOM/joomla/templates_c
chown apache.apache phpDocumentor/Converters/CHM/default/templates/joomla/templates_c
 

The most convenient way to use phpDocumentor is to create a configuration file that will hold all of your particular setups. You can create as many of these configuration files as you like for different purpose as you can select the one to use each time you run phpDocumentor.

Two such configuration files are to be found in the Joomla! documentation SVN and you will have copied them into the 'phpdoc/PhpDocumentor-1.3.0RC4/user' directory. The first of these, 'joomla11.ini' does a complete rebuild of the phpDocumentor output. The second, 'joomla11_mini_test.ini' compiles fewer files so that it reduces the regeneration time if you are making edits to formatting, layouts, etc. Take a look at them and you will see the kinds of things that can be configured.

You will need to edit a couple of statements in each of these files for use on your system. Using a standard text editor look for the 'target' statement and change it to the path that you want the phpDocumentor output files sent to. We set this up in the first step of this tutorial. Example:

;; where should the documentation be written?
;; legal values: a legal path
target = /var/www/html/joomla11
 

You also need to tell phpDocumentor where the Joomla! source code is held. You do this by changing the 'directory' statement. Notice that you will point phpDocumentor to the 'libraries/joomla' sub-directory of Joomla! as you don't want phpDocumentor to analyse the whole package, only the Joomla! API. Example:

;; comma-separated list of directories to parse
;; legal values: directory paths separated by commas
;;directory = /path1,/path2,.,..,subdirectory
directory = /home/chrisd/joomla-svn/trunk/libraries/joomla
 

You might also want to take a look at the 'output' statement. This controls which output formats are generated and you might want to limit this to a single output format while testing so that phpDocumentor completes its run more quickly. Example (which will produce output in HTML, CHM and PDF formats:

output=HTML:frames:DOM/joomla,CHM:default:joomla,PDF:default:default
 

Step 5: Copy the tutorial files

The last thing we need to do before we can run phpDocumentor is to copy the tutorials directory from your local working copy of the Joomla! documentation repository into your working copy of the Joomla! source code. In the last step we told phpDocumentor where to find the working copy of the Joomla! source code and in the next step we will actually run phpDocumentor against this code.

cd /home/chrisd/joomla-svn/trunk
cp -r /home/chrisd/joomladoc/trunk/* .
 

Step 6: Run phpDocumentor

The most convenient way to run phpDocumentor is from its web front-end, so start up your favourite web browser and point it at http://localhost/phpdoc/PhpDocumentor-1.3.0RC4. You should see a tabbed form. Click on the [Config] tab. This tab pane allows you to select which configuration file to use and using this method means you don't have to worry about entering anything into any of the other form fields.

Select 'joomla11.ini' from the drop-down list. Your screen should look like this:

TODO: INSERT SCREENSHOT HERE

Click [Go]. In the bottom frame you will see the output from the phpDocumentor compiler as it parses each of the source files and generates the output files. You may see some error messages but don't worry about them at this stage. The entire run may take a minute or two so be patient! When testing you will probably prefer to use the 'joomla11_mini_test.ini' configuration file instead as this takes substantially less time.

When the run is completed you should see "Operation Completed!!" in the bottom frame (you'll have to scroll down to see it though).

If you get 'Fatal error: Smarty error: unable to write to $compile_dir .....' then you forgot to change the ownership/permissions on the Smarty template in the converter directory. Look under Step 4 for details on how to fix this.

Step 7: Examine the output

Point your web browser to the output directory you specified, for example http://localhost/joomla11. You should see two sub-directories like this:

/var/www/html/joomla11
+- CHMdefaultConverter/
+- HTMLframesConverter/
 

If you get "Access denied" then check your Apache settings and the permissions/ownership of this directory.

If your directory is empty then you probably forgot to give Apache write access to this directory. I usually find that giving ownership of this directory to the Apache user is sufficient to fix this sort of problem. (See under Step 1 for a suggested fix).

Conclusion

Congratulations! You have successfully installed and configured the phpDocumentor package and you can now generate your own local copies of the Joomla! documentation in a variety of formats.

In the next tutorial we will look at how to make changes to the Joomla! documentation files and how to commit those changes back to the Joomla! documentation repository.

Acknowledgements

Thanks to Andrew Eddie for a comprehensive set of notes that became the basis for this tutorial.