Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 34 lines (19 sloc) 2.737 kb
361cdf0 Tobie Langel Added documentation.
authored
1 PDoc
2 ====
b171100 Tobie Langel Moving exported PDoc to git (yes, I know, that's lazy).
authored
3
361cdf0 Tobie Langel Added documentation.
authored
4 PDoc is an inline comment parser and JavaScript documentation generator written in Ruby. It is designed for documenting [Prototype](http://prototypejs.org) and Prototype-based libraries.
b171100 Tobie Langel Moving exported PDoc to git (yes, I know, that's lazy).
authored
5
e380743 Andrew Dupont Updated README.
savetheclocktower authored
6 PDoc uses [Treetop](http://treetop.rubyforge.org/), 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.
b171100 Tobie Langel Moving exported PDoc to git (yes, I know, that's lazy).
authored
7
e380743 Andrew Dupont Updated README.
savetheclocktower authored
8 Unlike other inline-doc parsers, PDoc does not rely on the JavaScript source code at all; it only parses the comments. This approach, though slightly more verbose, is much better at generating consistent, reliable documentation, and avoids the headaches encountered when documenting highly dynamic languages.
b171100 Tobie Langel Moving exported PDoc to git (yes, I know, that's lazy).
authored
9
e380743 Andrew Dupont Updated README.
savetheclocktower authored
10 ## Installation
11
63669c3 Tobie Langel Amend README.
authored
12 PDoc depends on Rake, your choice of markdown parser, and treetop, all of which can be obtained through RubyGems:
e380743 Andrew Dupont Updated README.
savetheclocktower authored
13
63669c3 Tobie Langel Amend README.
authored
14 gem install rake bluecloth treetop
78ee73d Andrew Dupont Prefer RDiscount over BlueCloth.
savetheclocktower authored
15
e380743 Andrew Dupont Updated README.
savetheclocktower authored
16 ## Usage
17
18 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 `lib/pdoc/runner.rb`).
19
20 ## How it works
21
22 The process of turning inline PDoc comments into a human-friendly document has two phases.
23
24 ### Parsing phase
25 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 `Treetop::Runtime::SyntaxNode`.
26
27 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.
28
29 ### Rendering phase
30 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](http://rdoc.sourceforge.net/ "RDoc - Document Generator for Ruby Source")'s.
31
32 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](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/index.html "erb: Ruby Standard Library Documentation"). Templates are modular, so it's quite easy to apply a custom "skin" to one's documentation pages.
33
34 Furthermore, generators themselves are modular; PDoc can, theoretically, parse once and render to several different targets (HTML, [DocBook XML](http://www.docbook.org/ "DocBook.org"), CHM, PDF, even [ScriptDoc](http://www.scriptdoc.org/ "ScriptDoc.org: Dynamic Language Documentation").) We hope many such generators will exist in the future.
Something went wrong with that request. Please try again.