This is a simple documentation tool for source code. It is a prototype which currently supports Perl (+Moose).
We generate HTML page from source code, and create a searchable index. This index contains elements both generated from documentation and from some basic code-intelligence (we recognize functions, classes, packages, etc).
Mainly, this was made to make code documentation as easy as possible. We do not use any special markup for parameters and such, and the amount of comments required in the source files is rather minimal. To make things easier to read however, it is a good idea to write code with good structure.
So, here is how some Moose code looks.
use MooseX::Declare;
=head1 Some class doing stuff in Perl
=cut
class MyClass {
=head2 This method does cool things.
Parameters: $i : A number
Returns: That number $i, incremented.
=cut
method some_method(Int $i) { return $i + 1; } }
This is what this tool does:
- It associates the first head1 with the package/class
MyClass. - head2 and double-hash elements are connected to the method/declaration below.
- We recognize some markup (or markdown, or pod) for formatting and links
Using the recursivedocumenter script, this can be done recursively for a set of modules. The generated index then allows searching across a bigger set of source files.
Finally, it's self-documenting: see [http://pkrusche.github.com/documenter].
Javascript/HTML:
- jQuery and jQueryUI
- highlight.js
- The famfamfam silk icons
- optionally: redcarpet (for more
github-like markdown
rendering).
You can install it by running
gem install redcarpetif you have Ruby.
Perl:
The follwing Perl modules are required. You can install them via CPAN (run cpan, then
install <modulename> for each of the modules shown below), or
using apt if you're on Ubuntu.
The template toolkit (used to process HTML and MD templates)
Things for markdown rendering:
The Perl Parser Interface:
Moose and MooseX (installing MooseX::Declare installs everything necessary)
This stuff is used for rendering the RSS feed.
Others: