The SketchApps development environment uses mechanized documentation,
in the form of "Court" (a YARD
YARD gathers information from both program source code
then generates a set of web pages.
Court merely tunes the process and output for SketchApps' needs.
Additional tools are under consideration; suggestions welcome...
Court is only thought to run on Mac OS X!
Please contact me if you would like to port it elsewhere...
is Loren Segal's enhanced reimplementation
I like the fact that it:
- allows explicit markup for parameters, return values, etc.
- parses the Ruby code, gathering much more information
- separates the concerns of data collection and reporting,
allowing variant formatters, post-processing of data, etc.
YARD markup format
YARD's markup format is a superset
of the popular RubyDoc format (used by RDoc
Here are some useful resources:
I'm a big fan of code folding
in text editors.
It lets me see content of current interest, hiding everything else.
To aid in this, I put comment blocks
the associated code section (eg, class, method),
causing them to disappear along with the code.
I'm also experimenting with semantic tags for comment blocks.
Court handles these markup variations, as well as some other issues.
- looks for a
SketchApps_dev directory and subsidiary app trees
- pre-processes each app tree, storing the output in
_Libraries/_Framework into each app's Tmp tree
- runs YARD on each Tmp tree, including
- Adds a "Court Index" page (
- tweaks the YARD output (eg, adding links to the "Court Index" page)
Court markup format
Court's markup format is based on YARD conventions, with minor variations.
script (a small wrapper for YARD) handles these variations,
as well as handling file manipulation and some output tweaking.
Court (ie, an interior yard) began as a way to allow comment blocks
to exist inside
the documented code sections (eg, module, class, method).
This approach is not currently in vogue with the Ruby community,
but it has several decades of precedent
and works well with code folding in text editors (eg, TextMate).
The following code segment illustrates how you might set up a Ruby script
to play nicely with Court.
- Court-style documentation blocks have a rather precise location. They must immediately follow the section header line (eg,
def) and have the same indentation level.
- Conventional (eg, RDoc, YARD) placement of documentation block is also allowed, using traditional location rules.
- A typical SketchApps distribution will have a motley collection of libraries, plugins, and scripts. To keep the namespaces distinct, all definitions should be enclosed in a class or module.
The following example script illustrates these points:
# awesome - Ruby script to do truly *awesome* stuff.
# @author Rich Morin
# This documents the +Awesome+ class.
# This documents the +main+ method.
# @return [void]
# This documents the +boring+ method.
# @return [void]
Preferably, ancillary comment blocks
should use "=begin court-<type> ... =end
" markup, eg:
court-coupling - class and instance variables, globals, etc.
court-legalese - copyrights, licenses, etc.
court-overview - architecture, caveats, usage, etc.
currently does nothing special with these blocks.
As noted above, Court is only thought to run on Mac OS X at present.
It also requires the YARD gem, SketchApps version 0.3,
Assuming that these preconditions are in place,
you can run the
script and examine its output as follows:
% open ~/Library/SketchUp/SketchApps_use/court_index.html
This wiki page is maintained by Rich Morin
an independent consultant specializing in software design, development, and documentation.
Please feel free to email
comments, inquiries, suggestions, etc!