Introduction

There are 2 possibilities to compile Zend Framework documentation (for 1.x or 2.x series):

• xsltproc : XSLT processor
• PhD: PHP tool used by http://php.net

I will show the 2 methods based on Ubuntu 11.10.

Get Zend Framework sources

For 1.x serie, you must use Subversion:

$ cd /path/you/want
$ svn co  http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/ .

To update your sources:

$ svn up

For 2.x serie, you must use Git: read http://framework.zend.com/wiki/display/ZFDEV2/Zend+Framework+Git+Guide

XSLT Processor

You need to install some tools:

# apt-get install autoconf make xsltproc libxml2-util docbook-utils docbook-xsl

At this stade, you can simply go in your favorite language directory to check the manual:

$ autoconf
$ ./configure
$ make check

You should obtain something like:

sed -e 's!@DOCBOOK_DTD@!http://framework.zend.com/docbook/xml/4.5/docbookx.dtd!' ../en/manual.xml.in > manual.xml
Checking the whole manual with /usr/bin/xmllint...
OK

In this result, you can see that you use ‘docbook.dtd’ located on Zend server. You can use the file located on your computer (downloaded with apt-get above) by adding:

$ export DOCBOOK_DTD=/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make check

Now, you have:

sed -e 's!@DOCBOOK_DTD@!/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd!' ../en/manual.xml.in > manual.xml
Checking the whole manual with /usr/bin/xmllint...
OK

If the final result is ‘OK’, yon can compile the documentation in HTML with:

$ make

But this will use XSL stylesheets located on Zend server. In the initial ‘apt-get’ you downloaded these stylesheets. To automagically use them you should add:

$ export DOCBOOK_XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make

It took me 19 minutes to compile English HTML documentation for trunk r24580. This is a rough version (no images for design, no color).

If you like PDF version of the documentation (around 1860 pages), you can also compile it with FOP, you need:

# apt-get install fop
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make pdf

It took me 6 minutes to compile English PDF documentation for trunk r24580. This is a rough version (no images for design, no color).

If you prefer the CHM version, it’s a little more complicated on Ubuntu but it’s possible! First step you need:

# apt-get install wine

Then start at least one time Wine (Notepad for example) to generate default configuration. After that you can use the following script (provided in http://appdb.winehq.org/objectManager.php?sClass=version&iId=2978&iTestingId=15284):

#!/bin/bash -e
# -e Exit immediately if a command exits with a non-zero status.

# This installs Microsofts HHC (HTML Help Compiler)
# Copyright 2011 Timo Richter and others.
# Licensed under GNU GPLv3
# Depends on: wine, wget, cabextract
#
# Usage of HHC: wine c:\\htmlhelp\\hhc.exe c:\\test\\htmlhelp.hhp
#
# Changes: Set installation directory to c:\htmlhelp
# Copy also itcc.dll, this is neccessary
# No execution of htmlhelp.exe installer needed
# Abortion of install if anything fails, e.g. the download of HHC.
#

echo "Please wait"

cd "$(dirname "$0")" # cd to path of this script

WINEPREFIX=${WINEPREFIX:=$HOME/.wine}
test -d "$WINEPREFIX" || wineprefixcreate 2>> /dev/null
HHDIR="${WINEPREFIX}/dosdevices/c:/htmlhelp"
mkdir "$HHDIR"

# Setup the registry
# Set Wine's Windows version to Windows 2000 (or above), and add an override to use the native itss.dll, both via winecfg.
# wine regedit htmlhelp.reg

After chmod+x the script then launch it.

Now you have HTML Help Workshop on your machine, you need to create files to generate the CHM. The first DOCBOOK_XSL (chunk.xsl) doesn’t allow to create CHM, you need to change it to htmlhelp.xsl:

$ export DOCBOOK_XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl/htmlhelp/htmlhelp.xsl
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make

After some minutes (always 19 minutes in my case), you obtain all the files and especially a new one in ‘html’ subdirectory ‘htmlhelp.hhp’. You have to provide this file to HTML Help Workshop:

$ wine /home/mikaelkael/.wine/drive_c/htmlhelp/hhc.exe html/htmlhelp.hhp

You obtain the CHM in ‘html’ subdirectory, something like: ‘Zend_Framework_[LANG].chm’. It’s always without any colors or images.

PhD

First step, you need to retrieve PhD and dependencies from Zend sources:

$ cd /path/you/want
$ svn co http://framework.zend.com/svn/framework/build-tools/trunk/build-tools/docs/ build-tools

To update your sources:

$ svn up

Then you have to convert documentation files in Docbook4 to Docbook5:

$ autoconf
$ ./configure
$ make manual.xml
$ xsltproc --xinclude /path/to/build-tools/db4-upgrade.xsl manual.xml > manual-db5.xml

Now you can build the documentation:

/path/to/build-tools/pear/phd -g 'phpdotnet\phd\Highlighter_GeSHi' --xinclude -f zfpackage -d manual-db5.xml

You obtain in less than 1 minute:

[15:20:56 - Indexing] Indexing...
[15:21:00 - Indexing] Indexing done
[15:21:00 - Rendering Style] Running full build
[15:21:00 - Rendering Format] Starting ZF-Package-Chunked-XHTML rendering
[15:21:39 - Rendering Format] Finished rendering

You will find the documentation in ‘output’ subdirectory. With this version, all programlisting are syntax highlighted.

Enhancements

To go further, you can find the scripts I use to generate http://doczf.mikaelkael.fr in GitHub: https://github.com/mikaelkael/zfdocumentor. The are based on xsltproc. I am planning to migrate to PhD because of the time to render a documentation.