Arti: Installation and Use

Installation and Use

These are very early days in Arti's development. So, things are quite likely to break, change, etc. Although I cannot provide unlimited free support for Arti, I'm quite willing to answer simple questions, handle bug reports and other feedback, etc. So, please feel free to send me a note.

Arti is (only) a toolkit. To take proper advantage of its tools, let alone customize and extend them for a particular development project, involves a bit of a learning curve and perhaps some Real Work (TM). If your Rails developers are otherwise engaged, you may wish to consider purchasing installation, configuration, customization, and/or maintenance services.

Note: Arti was developed on (version 10.4 of) Apple's Mac OS X, a BSDish Unix variant. It should be easy to use on other Unix variants, but your mileage may vary. I can't help you with OS-related problems, but I'll happily accept bug reports, comments, suggestions, etc.
Getting Arti to work on other operating systems, such as Microsoft Windows, may pose a few challenges, despite the acclaimed portability of Ruby scripts. In particular, the diagrams.rb script (needed for normal use) and the dist_arti.rb script (generally not needed) make use of the system() call. If you are running Windows, but need some Unixish commands (etc.), you really should look into Cygwin.

Arti may be employed in either Merged or Remote mode. In Merged mode, Arti shares the target app's file tree and server access. In Remote mode, Arti runs as an entirely separate app, accessing the target app's file tree for information. Remote mode is a lot easier to set up (and probably what you want, anyway), so we'll start there.

Remote Mode

Remote mode requires minimal changes to the target app. To keep RDoc happy, there needs to be a "doc" directory and a "doc/README_FOR_APP" file. Arti will create these if they don't already exist, but you may want to edit "README_FOR_APP" to add some real information about the target app.

Instant Gratification: `arti_ar`

Unless you're already serving this page from a local server, you'll need to do a bit of setup:

Make sure you have the "syntax" gem (used for syntax coloring of Ruby source code).
Download and unpack the Arti distribution.
Recreate the example app from the "BASE_ar" tree and the "arti.diff" file.
Rebuild the app's reference files, using "doit".
Start an HTTP server for the example app.

The "arti_ar" app is really simple; it just examines and reports on its own code base:

  % gem install syntax
  % cd [some_convenient_location]
  % curl -O http://www.cfcl.com/rdm/Arti/downloads/arti-[version].tgz
  % tar xzf arti-[version].tgz
  % cd arti-[version]
  % script/recreate arti
  % cd remote/arti_ar
  % script/arti/doit
  % script/server -p3000

Point your web browser at "http://localhost:3000"; you should see the "Welcome to Arti!" page. Take some time to skim through it and find out what Arti is all about. Then, visit the Files, Plots, RDoc, Rules, and Stats pages to see what kinds of output Arti provides.

A Real App (TM): `mephisto_ar`

Mephisto is a well-regarded Rails-based weblog engine (etc) with all sorts of snazzy features. For our current purposes, however, it's just a substantial target app which we can use Arti to document. So...

Download and unpack a copy of Mephisto. If you put it next to arti-[version], "mephisto_ar" will know where to find it. Otherwise, you'll need to edit the "target.yml" file in "mephisto_ar/config".

  % cd arti-[version]
  % script/recreate mephisto
  % cd remote/mephisto_ar
  % script/arti/doit
  % script/server -p3001

The "doit" script runs assorted data-harvesting code, using the target app's code base as input. The resulting information is stored as YAML files in the "doc" tree. Arti uses these files, rather then the actual code base, as the basis for its generated web pages. So, whenever you change the code base, you'll need to re-run "doit" to get up-to-date documentation.

Your Own App: `xyz_ar`

So much for "canned" examples. Now, let's point Arti at something you really care about: one of your own Rails applications. No guarantees made or implied, but this should be (relatively) easy.

Generate a fresh copy of the "arti_ar" tree.
Rename it to "xyz_ar"
On Unixish systems, this can be accomplished by "mv arti_ar xyz_ar".
Edit "app/controllers/application.rb".
Change ":session_key" to something distinctive, as:
```
    session :session_key => '_xyz_ar_session_id'
```
Edit "config/arti/target.yml".
Adjust the description, name, path, and URL as needed for the target application.

  % script/arti/doit
  % script/server -p3002

With luck, "http://localhost:3002" will respond with lots of useful information about your app. As you look over the results, however, you are certain to see some glitches. Here are some things you can do:

File extensions (easy)
Look over the Stats page. It's quite possible that Arti won't recognize some of the file extensions it sees in the target app. Add (descriptions for) them to "ext_descs" (in "config/arti/reference.yml"), then try again.
File tree metadata (moderate)
On the Files page, you may see '???' in the Description field. This is an indication that the file tree metadata needs an entry to recognize and define the path in question.
Examine (but do not modify) "config/ft_default.yml". This is where "well known" files and directories get defined. The format is based on YAML, but you'll also need to know a bit of Ruby (especially regular expressions) to understand it..
Now, add some entries to "config/ft_override.yml". Start slowly, to be sure you understand the syntax and semantics of the entry format. Many definitions will seem rather obvious. Persevere; the result will be a nice-looking file list that programmers won't have to puzzle over to understand.
Each time you finish a set of edits, run "doit" and then refresh the Files page in your web browser. When you are happy with the results, move on.
Diagram configuration files (moderate)
Arti should produce reasonable plots for each View in your app, but they may be missing some key entities and relationships. Each View will have a "hints" file in "config/arti/diagrams/cv_hints". These YAML files help Arti to create the "production" plot specification files in "doc/app/arti/dot").
Look over the latter, along with ".../gv_meta.yml" then add hints to the former and try again. The basic idea is that you are telling Arti about entities and relationships (by path name), so that it can include them in its diagrams.
Look over the View Linkage files (".../vl_*.yml") in the other instances of Arti. Using these as an example, create similar files for your own app. Don't try to include every link; these are intended as overview diagrams!
Technologies (easy)
Look over the Techs page. It's quite possible that Arti won't recognize some of the plugins and vendors it sees in the target app. If so, it won't render their names as links. If you feel motiviated to do so, look up appropriate URLS for these, add them to "plugins" or "vendors" (as appropriate) in "config/arti/techs.yml"), then try again. When you get done, send me the new entries!

At this point, the basic configuration is done. This would be a good time to send me a note. Tell me what app you're documenting, how the process went, and what deficiencies you found in Arti. If you had to modify "config/arti/reference.yml" or put common items in any of the other config files, tell me about it so that I can add them to Arti.

Merged Mode

Merged mode can be convenient for debugging, but it adds complexity to the target app's file tree and may well necessitate adjustment of routing tables. So, as noted above, this is probably not the best place to begin. However, if you're feeling sufficiently motivated, start with the Cheating Hangman.

The Cheating Hangman

Hangman is a Rails-based word game, using a read-only database for reference. So, in order to run the game, you must create and populate a MySQL database. The instructions for this are too detailed for this document; see ".../arti_hangman/README.Hangman".

Migrating Arti to Another Application

Once the Arti files have been copied over to another app, minimal work is needed to make it operational. The first step is to get the files in place. After making sure that you have backups in place, run:

    % cd .../arti_hangman
    % script/arti/arti_copy.rb [path_to_your_target_app]

Arti's files are scattered across the application file tree, but the Rails conventions make their installation easy and predictable. After running "arti_copy.rb", your target app should have the following files and directories:

    app/controllers/arti_controller.rb
    app/helpers/arti_helper.rb
    app/views/arti/*.rhtml
    config/arti/*.yml
    doc/arti/{dot,misc}
    lib/arti.rb
    public/stylesheets/arti.css
    script/arti/*
    test/functional/arti_controller_test.rb
    {README,VERSION}.Arti

With the Arti files in place, you can begin to make some tweaks. Look in the Hangman's application.rhtml file. Note the presence of the "stylesheet_link_tag 'application' command. Add this to your own file. You may also want to copy some of the links from the Hangman's header bar to an appropriate view (or layout) in your application. This will make it much easier to get to the Arti pages.

Finally, have Arti update its reference files:

    % cd [your_target_app]
    % script/arti/doit

And try out the Arti pages...

Arti: Arti