Developer docs

[Tim Penhey]

Here are some notes from the discussion we had last week.

A key part was to make sure that the developer documentation was
available outside the actual source tree.  We thought something like:

   https://juju.ubuntu.com/dev/ - Developer Documentation

The actual files are in the source tree in the doc directory, and we
have a process (read script magic) that takes the markdown formatted
local files and creates pretty HTML for the website.  This should happen
automagically every time we have a stable release.

There was a list of topics that we need to make sure are covered:

  * Architecture overview
  * API overview
  * Writing new API calls
  * What is in state (our persistent store - horrible name, I know)
  * How the mgo transactions work
  * How to write tests
     * base suites
     * environment isolation
     * patch variables and environment
     * using gocheck (filter and verbose)
     * table based tests vs. simple tests
     * test should be small and obviously correct
  * Developer environment setup
  * How to run the tests
     * juju test <filter> --no-log (plugin)


And a side note:
  https://juju.ubuntu.com/install/ should say install juju-local

Now we need people to put their hands up and write the docs.  Since I'm
first, I get to choose first (bwahaha), and I choose the "how to write
tests".

I'm also pretty keen on the 'juju-test' plugin.  Partly because I don't
like typing the command line args all the time for verbose logs and
filter stuff, so would like it easier.

I think a side part of the juju-test plugin is that it is conceivable
that the plugin could output subunit output (optionally) for hooking
into other test tools.

I have a feeling that there will be some files in the doc directory that
we don't want up on the website (maybe), so I envision that someone will
end up writing the script that manages the structure and conversion of
the raw files.

Comments or claims?

Tim