PHPDocumentor Fork (earthli-v2)

PHPDoc is a popular tool for generating documentation for PHP projects. I made a whole lot of improvements to it for PHP5 and updated all the skins to look less boxy, have nicer and more informative icons and be easier to use, and then created an earthli fork. This article includes a full feature list and screenshots.

The earthli WebCore (the software that runs this web site) is open-source. It is also relatively well-documented. The documentation is generated using PHPDoc, but a better version than that available in the main fork of PHPDoc found on the main site or in SourceForge.

Though PHPDoc does a decent job of gathering information and making it available to the templates, there are a few problems with the main fork:

• Insufficient support for some of the newer PHP5 features
• Uneven information availability in the different templates
• Pretty old and staid templates

A long time ago—when PHP4 was still young—I contributed a whole new set of templates—modestly called “earthli” and “earthli:DOM”—to the project and brought the rendering up to a decent level. There were still problems, but it was—in my eyes—worlds better than any of the existing templates.

Things stayed like that for a while.

Then I ported my framework from PHP4 to PHP5 in early 2010 and discovered that PHPDoc was again limping along a bit, generating output that no longer met my standards.

Features of earthli-v2

So, I made a lot of improvements and again basically rewrote one set of templates (this time called “earthli-v2”) that I thought looked clean and offered the following features:

• The HTML that is generated is purely structural, leaving formatting, coloring and other skinning up to the options.
• The clean structure means the files look fine without icons or styling and also should be much more accessible: both for people and processing tools.
• There are no more extra formatting containers and all presentational tables have been removed.
• The HTML now validates 100% for all generated pages.
• The CSS is cleanly separated into individual files and no longer includes anything that is not used. There is a base stylesheet and icon and coloring/positioning skins that allow complete control through CSS without touching the templates at all. So authors can define and tweak skins simply by adding a folder with a few CSS files and choosing that skin in the options file.
• Options include:

  1. Encoding: UTF-8 and ISO-8859-1 are supported; defaults to UTF-8.
  2. Content Type: XHTMLand HTML are supported; defaults to HTML.
  3. Default Type: Controls the type used when none other is given: common values are object, stdClass, mixed; defaults to mixed.
  4. Source Links: Controls whether each element includes a link to source (the “#” in the screenshots); links can be included in summaries, indexes or both.
  5. Source Formatting: Control whether source is formatted using non-breaking spaces or regular spacing and style-sheets with control over tab-size.
  6. Access/Abstract Tags: Control whether access and abstract tags are generated; since these properties are also indicated by the icon, defaults to false.
  7. Icon Mode: Control how icons are generated: valid values are css, img and none; defaults to css.
  8. Dynamic: Control over whether Javascript is used; defaults to false
  9. Section Inclusion: Control which sections are generated in the tree (as well as icon mode); defines, functions and variables can be turned on and off; default is to include everything in the tree.
  10. Skin: Control the look and feel: the default (a PHPDoc standard) and earthli skins are included; defaults to earthli.

Screenshots

The old style isn’t horrible, but it’s a bit dated, with too many borders, blurry icons and too many bold fonts.

The new style is cleaner, has far fewer borders, better margins and alignments and nicer icons (for all elements, with access visibility for all element types) as well as much more legible placement and more information, including direct links to source for all elements, much nicer signature-formatting and tamer colors.

Downloading the Fork

I was in contact with the project maintainer but was never able to upload my changes into the main branch of PHPDoc. There have been no updates on the main line since late 2009 and I don’t know whether the project has died or not. I only just realized that I never officially published my changes, so I’m officially making the earthli fork available as a Mercurial repository or as a compressed archive.