Update documentation

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)

[gary.poster, 2012-12-14 17:10:29]

Please take a look.

[matthew.scott, 2012-12-14 17:29:07]

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

[gary.poster, 2012-12-14 17:32:55]

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.

[frankban, 2012-12-14 17:46:51]

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.

[gary.poster, 2012-12-14 18:05:16]

*** 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

[gary.poster, 2012-12-14 18:08:33]

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...

::

[teknico, 2012-12-17 11:47:26]

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.

[gary.poster, 2012-12-17 12:33:38]

On Dec 17, 2012, at 6:47 AM, nicola.larosa@canonical.com 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, 2012-12-17 14:11:11]

> 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. :-/