Developer docs

[Nick Veitch]

I volunteer to:
  * Manage the markdown->html stuff
  * Create a sensible structure for the docs
  * Make helpful suggestions like "shouldn't there be a section on how
providers work and how to write your own?"

On Wed, May 7, 2014 at 6:35 AM, Frank Mueller
<frank.mueller at canonical.com> wrote:
> Hi,
>
> I'm still on silver wedding journey, so I'm not snchronized with all
> discussions. Currently I'm supporting Nick writing the docs from the user
> perspective, but I'm thinking about the dev docs since a longer time. So I'm
> raising my hand for writing those docs when I'm back next week.
>
> mue
>
> Am Mittwoch, 7. Mai 2014 schrieb 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
>>
>> --
>> Juju-dev mailing list
>> Juju-dev at lists.ubuntu.com
>> Modify settings or unsubscribe at:
>> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
>
>
> --
> ** Frank Mueller <frank.mueller at canonical.com>
> ** Software Engineer - Juju Development
> ** Canonical
>
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>



-- 
Nick Veitch
nick.veitch at canonical.com