Improve documentation, including improv intro

Improve documentation, including improv intro

Introduce improv as the easiest way to develop with pyJuju.  Also aggregate the command lines to make it easier for developers, and make a few other documentation changes as I went.

https://code.launchpad.net/~gary/juju-gui/trunk/+merge/144846

(do not edit description out of merge proposal)

[gary.poster, 2013-01-25 05:12:01]

Please take a look.

[frankban, 2013-01-25 10:45:56]

Land with minor changes (see below).

Hi Gary, this branch really improves our documentation!
Thank you!

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

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode31
HACKING:31: Go ahead and use the branch's sample.json file to pre-populate the
Since large.json is quoted in this paragraph, maybe you might want to quote
sample.json too.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode43
HACKING:43: python-virtualenv to build the Google Closure linter tools locally::
Much better, thanks!

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode47
HACKING:47: sudo apt-get install nodejs npm imagemagick lbox python-sphinx
python-tz python-virtualenv
Add python-yaml?

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode60
HACKING:60: located on your path (e.g., by linking it into ~/bin).
Maybe double ticks around ~/bin?

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode75
HACKING:75: Note that the Makefile supports "make help" to try to introduce some
of the
Elsewhere in the doc, we use double ticks around make commands.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode178
HACKING:178: sudo apt-get install python-sphinx python-yaml
python-sphinx already installed in the initial setup (Developer Install).
python-yaml should be already installed too (make docs requires it, see above).
However, if you intended to repeat instructions here to give more context, then
leave as is.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode191
HACKING:191: Proposing Branches
Great!

https://codereview.appspot.com/7203058/diff/1/docs/process.rst
File docs/process.rst (right):

https://codereview.appspot.com/7203058/diff/1/docs/process.rst#newcode71
docs/process.rst:71: Once you have two approving reviews (and no disapproving
reviews, or an
a resolution

[teknico, 2013-01-25 10:49:11]

Land with changes.

Thanks for this, very nice. See some comments below.

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

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode10
HACKING:10: Before you get the GUI, first you need to get Juju.  For PyJuju, we
use a
"...For PyJuju, the original Python-based Juju implementation, we use..."

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode11
HACKING:11: custom branch of Juju that supplies the websocket API we need.  (Go
Juju will
"...GoJuju, the newer Go-based Juju implementations, will..."

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode31
HACKING:31: Go ahead and use the branch's sample.json file to pre-populate the
``sample.json``

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode32
HACKING:32: environment.  In the future, you might want to investigate the
"large.json"
``large.json`` file

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode40
HACKING:40: based development tools, so you will need ``nodejs`` & ``npm`` from
Chris
Is "&" in place of "and" Strunk'n'White-compliant? ;-P

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode58
HACKING:58: If you recieve an error installing phantomjs, you can manually
download and
receive

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode75
HACKING:75: Note that the Makefile supports "make help" to try to introduce some
of the
Thanks for adding this. :-)

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode77
HACKING:77: password you should use with improv is "admin," despite the help
text you see.
Uhm, that's unfortunate.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode88
HACKING:88: have bit-rotted and we haven't felt the need to update them.  If you
get them
have not

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode143
HACKING:143: runner. If you need to debug a test in the browser use ``make
test-server``.
Please add a comma after "browser", while you're at it.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode195
HACKING:195: Gustavo Niemeyer has `a helpful blogpost <http://goo.gl/oHP1l>`_
about this
As discussed with benji, let's avoid URL shorteners. If the URL is too long to
sit comfortably inside the text, it can be moved below the paragraph.

https://codereview.appspot.com/7203058/diff/1/docs/process.rst
File docs/process.rst (right):

https://codereview.appspot.com/7203058/diff/1/docs/process.rst#newcode51
docs/process.rst:51: - Propose your branch with lbox (see `this blog post
<http://goo.gl/oHP1l>`_)
Ditto about URL shorteners.

https://codereview.appspot.com/7203058/diff/1/docs/process.rst#newcode68
docs/process.rst:68: to work it out with someone else instead, but it's much
better to work
it is

[gary.poster, 2013-01-25 15:48:53]

*** Submitted:

Improve documentation, including improv intro

Introduce improv as the easiest way to develop with pyJuju.  Also aggregate the
command lines to make it easier for developers, and make a few other
documentation changes as I went.

R=frankban, teknico
CC=
https://codereview.appspot.com/7203058

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

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode10
HACKING:10: Before you get the GUI, first you need to get Juju.  For PyJuju, we
use a
On 2013/01/25 10:49:11, teknico wrote:
> "...For PyJuju, the original Python-based Juju implementation, we use..."

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode11
HACKING:11: custom branch of Juju that supplies the websocket API we need.  (Go
Juju will
On 2013/01/25 10:49:11, teknico wrote:
> "...GoJuju, the newer Go-based Juju implementations, will..."

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode40
HACKING:40: based development tools, so you will need ``nodejs`` & ``npm`` from
Chris
On 2013/01/25 10:49:11, teknico wrote:
> Is "&" in place of "and" Strunk'n'White-compliant? ;-P

Heh.  :-) Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode47
HACKING:47: sudo apt-get install nodejs npm imagemagick lbox python-sphinx
python-tz python-virtualenv
On 2013/01/25 10:45:56, frankban wrote:
> Add python-yaml?

Good catch, thank you.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode58
HACKING:58: If you recieve an error installing phantomjs, you can manually
download and
On 2013/01/25 10:49:11, teknico wrote:
> receive

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode60
HACKING:60: located on your path (e.g., by linking it into ~/bin).
On 2013/01/25 10:45:56, frankban wrote:
> Maybe double ticks around ~/bin?

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode75
HACKING:75: Note that the Makefile supports "make help" to try to introduce some
of the
On 2013/01/25 10:45:56, frankban wrote:
> Elsewhere in the doc, we use double ticks around make commands.

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode77
HACKING:77: password you should use with improv is "admin," despite the help
text you see.
On 2013/01/25 10:49:11, teknico wrote:
> Uhm, that's unfortunate.

Yeah, mildly.  The build's help text can't react to the environment the way it
can within the charm.  We could switch the default help text to talk about admin
because that is the common case for the prod.  The current looks more like a
real "prod" usage would though.  <shrug>  I'm happy for someone to change it but
I don't feel the urge myself.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode88
HACKING:88: have bit-rotted and we haven't felt the need to update them.  If you
get them
On 2013/01/25 10:49:11, teknico wrote:
> have not

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode143
HACKING:143: runner. If you need to debug a test in the browser use ``make
test-server``.
On 2013/01/25 10:49:11, teknico wrote:
> Please add a comma after "browser", while you're at it.

Done.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode178
HACKING:178: sudo apt-get install python-sphinx python-yaml
On 2013/01/25 10:45:56, frankban wrote:
> python-sphinx already installed in the initial setup (Developer Install).
> python-yaml should be already installed too (make docs requires it, see
above).
> However, if you intended to repeat instructions here to give more context,
then
> leave as is.

No, thanks, I want to clean this up to.  I made some changes like the ones
elsewhere.

https://codereview.appspot.com/7203058/diff/1/HACKING#newcode195
HACKING:195: Gustavo Niemeyer has `a helpful blogpost <http://goo.gl/oHP1l>`_
about this
On 2013/01/25 10:49:11, teknico wrote:
> As discussed with benji, let's avoid URL shorteners. If the URL is too long to
> sit comfortably inside the text, it can be moved below the paragraph.

Done.

https://codereview.appspot.com/7203058/diff/1/docs/process.rst
File docs/process.rst (right):

https://codereview.appspot.com/7203058/diff/1/docs/process.rst#newcode51
docs/process.rst:51: - Propose your branch with lbox (see `this blog post
<http://goo.gl/oHP1l>`_)
On 2013/01/25 10:49:11, teknico wrote:
> Ditto about URL shorteners.

Done.

https://codereview.appspot.com/7203058/diff/1/docs/process.rst#newcode68
docs/process.rst:68: to work it out with someone else instead, but it's much
better to work
On 2013/01/25 10:49:11, teknico wrote:
> it is

Done.

https://codereview.appspot.com/7203058/diff/1/docs/process.rst#newcode71
docs/process.rst:71: Once you have two approving reviews (and no disapproving
reviews, or an
On 2013/01/25 10:45:56, frankban wrote:
> a resolution

Done.

[gary.poster, 2013-01-25 15:50:52]

Thank you very much for the great and detailed reviews, Nicola and Francesco.  I
made all requested changes.

Gary