Merge lp://staging/~gary/charms/precise/juju-gui/update-docs into lp://staging/~juju-gui/charms/precise/juju-gui/trunk

Reviewers: mp+139968_code.launchpad.net,

Message:
Please take a look.

Description:
Update documentation

The README was incorrect, and did not warn users about current issues
with the charm. Update the README and HACKING documentation to give
more complete instructions and better detail.

https://code.launchpad.net/~gary/charms/precise/juju-gui/trunk/+merge/139968

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/6945058/

Affected files:
   M HACKING.txt
   M README.txt
   A [revision details]
   M revision

LGTM with a few minors.

Thanks for the update, and handling the questions on IRC.

https://codereview.appspot.com/6945058/diff/1/HACKING.txt
File HACKING.txt (right):

https://codereview.appspot.com/6945058/diff/1/HACKING.txt#newcode98
HACKING.txt:98: Unfortunately, we have not found LXC-based Juju
environments to be reliable
Two paragraphs in a row starting with the same word is a little awkward;
I think the 'Unfortunately' in the second paragraph may be unnecessary
("Currently, running...is quite slow, however, ...")

https://codereview.appspot.com/6945058/diff/1/README.txt
File README.txt (right):

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode73
README.txt:73: when run withing the charm, the GUI appears to not be
connecting properly to
s/withing/within

https://codereview.appspot.com/6945058/

Thanks. :-)

https://codereview.appspot.com/6945058/diff/1/HACKING.txt
File HACKING.txt (right):

https://codereview.appspot.com/6945058/diff/1/HACKING.txt#newcode98
HACKING.txt:98: Unfortunately, we have not found LXC-based Juju
environments to be reliable
On 2012/12/14 17:29:07, matthew.scott wrote:
> Two paragraphs in a row starting with the same word is a little
awkward; I think
> the 'Unfortunately' in the second paragraph may be unnecessary
("Currently,
> running...is quite slow, however, ...")
Oops. :-) Thanks, good catch. Fixed as suggested.

https://codereview.appspot.com/6945058/diff/1/README.txt
File README.txt (right):

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode73
README.txt:73: when run withing the charm, the GUI appears to not be
connecting properly to
On 2012/12/14 17:29:07, matthew.scott wrote:
> s/withing/within

Fixed, thank you.

https://codereview.appspot.com/6945058/

Land with changes.

This branch looks good Gary, thanks for these documentation improvements
and clean up.
Just some minor comments follow.

https://codereview.appspot.com/6945058/diff/1/HACKING.txt
File HACKING.txt (right):

https://codereview.appspot.com/6945058/diff/1/HACKING.txt#newcode19
HACKING.txt:19: `getting started
<https://juju.ubuntu.com/docs/getting-started.html>`. If you
Missing underscore at the end of the rst link.

https://codereview.appspot.com/6945058/diff/1/README.txt
File README.txt (right):

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode15
README.txt:15: First, there is no security. Anyone who can connect to
your machines can
Thanks for adding this warning.

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode40
README.txt:40: $ juju deploy cs:~juju-gui/precise/juju-gui
Should this be a code block?

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode49
README.txt:49: $ watch juju status
Same as above.

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode52
README.txt:52: something that looks like this:
We should add another colon here and indent the following juju status
output example, so that rst, considering that a code block, can
correctly compile the file.

https://codereview.appspot.com/6945058/

*** Submitted:

Update documentation

The README was incorrect, and did not warn users about current issues
with the charm. Update the README and HACKING documentation to give
more complete instructions and better detail.

R=matthew.scott, frankban
CC=
https://codereview.appspot.com/6945058

https://codereview.appspot.com/6945058/

Thanks Francesco. Good catches. I ran the files through rst2html a few
times and fixed some other bits I saw too. I forget how easy it is to
actually try the ReST out. :-P

Gary

https://codereview.appspot.com/6945058/diff/1/HACKING.txt
File HACKING.txt (right):

https://codereview.appspot.com/6945058/diff/1/HACKING.txt#newcode19
HACKING.txt:19: `getting started
<https://juju.ubuntu.com/docs/getting-started.html>`. If you
On 2012/12/14 17:46:51, frankban wrote:
> Missing underscore at the end of the rst link.

Done.

https://codereview.appspot.com/6945058/diff/1/HACKING.txt#newcode108
HACKING.txt:108: If Jitsu generates errors about not being able to
bootstrap...::
Changed to ...\n:: for better rendering.

https://codereview.appspot.com/6945058/diff/1/README.txt
File README.txt (right):

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode33
README.txt:33: and then run the usual bootstrap command.
Added a code block here too.

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode40
README.txt:40: $ juju deploy cs:~juju-gui/precise/juju-gui
On 2012/12/14 17:46:51, frankban wrote:
> Should this be a code block?

Done.

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode49
README.txt:49: $ watch juju status
On 2012/12/14 17:46:51, frankban wrote:
> Same as above.

Done.

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode52
README.txt:52: something that looks like this:
On 2012/12/14 17:46:51, frankban wrote:
> We should add another colon here and indent the following juju status
output
> example, so that rst, considering that a code block, can correctly
compile the
> file.

Done.

https://codereview.appspot.com/6945058/diff/1/README.txt#newcode87
README.txt:87: For now, though, install Jitsu...::
Changed this to the following, because it renders better (the "::" is
omitted)

For now, though, install Jitsu...

::

https://codereview.appspot.com/6945058/

Thanks for these changes, Gary. Admittedly I was a bit lazy when writing
the first revision of the README, your changes make it much more
thorough.

gary.poster wrote:
> I ran the files through rst2html a few times and fixed some
> other bits I saw too. I forget how easy it is to actually
> try the ReST out. :-P

You don't need to run the rst2html command directly, just "make sphinx"
from the root directory, or equivalently "make html" from the docs/ one.

https://codereview.appspot.com/6945058/

On Dec 17, 2012, at 6:47 AM, <email address hidden> wrote:

> Thanks for these changes, Gary. Admittedly I was a bit lazy when writing
> the first revision of the README, your changes make it much more
> thorough.
>
> gary.poster wrote:
>> I ran the files through rst2html a few times and fixed some
>> other bits I saw too. I forget how easy it is to actually
>> try the ReST out. :-P
>
> You don't need to run the rst2html command directly, just "make sphinx"
> from the root directory, or equivalently "make html" from the docs/ one.

Not in the charm, yeah?

>
>
> https://codereview.appspot.com/6945058/

> teknico wrote.
>> You don't need to run the rst2html command directly, just
>> "make sphinx" from the root directory, or equivalently
>> "make html" from the docs/ one.

gary.poster wrote:
> Not in the charm, yeah?

Oh my. No, not in the charm.

Apparently my head isn't yet totally wrapped around the fact that we're
working with two distinct environments with different facilities. :-/

https://codereview.appspot.com/6945058/