PDoc uses Treetop, a Ruby-based DSL for text parsing and interpretation, and its own ActionView-inspired, ERB-based templating system for HTML generation. Other documentation generators (e.g., DocBook XML) are planned.
PDoc depends on Rake, BlueCloth, and treetop, all of which can be obtained through RubyGems:
gem install rake BlueCloth treetop
As an alternative to BlueCloth, you can use RDiscount, which is faster than BlueCloth and compatible with Ruby 1.9.1. PDoc will prefer RDiscount if it is found.
For hints on how to run PDoc on the command line, consult the built-in Rake tasks (in
Rakefile) and the
PDoc::Runner class (in
How it works
The process of turning inline PDoc comments into a human-friendly document has two phases.
In this phase, the source files are scanned for PDoc comments, then parsed with the Ruby files generated from the Treetop language grammar. The product of this phase is a tree full of specialized classes, all of which inherit from
The root of the tree is an instance of
Documentation::Doc. It comprises one or more instances of
Documentation::Section; which in turn comprise language elements like namespaces, classes, constants, etc., all of which have class representations.
Next, PDoc asks a generator how to translate this abstract tree into a hierarchical document. The default generator outputs organized HTML in a manner similar to RDoc's.
The HTML generator (
PDoc::Generators::Html) has associated templates (in the
templates directory) that accept syntax nodes and echo their metadata onto the page using ERB. Templates are modular, so it's quite easy to apply a custom "skin" to one's documentation pages.
Furthermore, generators themselves are modular; PDoc can, theoretically, parse once and render to several different targets (HTML, DocBook XML, CHM, PDF, even ScriptDoc.) We hope many such generators will exist in the future.