Merge lp:~gary/charms/precise/juju-gui/markdown into lp:~juju-gui/charms/precise/juju-gui/trunk

[Gary Poster]

Move markdown files to .md extension

The charm store needs the document file names to end with .md in order to process them as markdown.

https://codereview.appspot.com/6939067/

[Gary Poster (gary)]

Reviewers: mp+140279_code.launchpad.net,

Message:
Please take a look.

Description:
Convert docs from ReST to Markdown

We discovered today that ReST is not actully supported by the charm
store, and is not intended to be supported by the charm store or the GUI
any time soon. Convert the docs to Markdown, so they render nicely.

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

(do not edit description out of merge proposal)

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

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

[Gary Poster (gary)]

self-reviewing doc changes.

As a note, I used retext to generate and test the Markdown. Works
nicely, with live update.http://sourceforge.net/p/retext/home/ReText/

https://codereview.appspot.com/6939067/

[Gary Poster (gary)]

*** Submitted:

Convert docs from ReST to Markdown

We discovered today that ReST is not actully supported by the charm
store, and is not intended to be supported by the charm store or the GUI
any time soon. Convert the docs to Markdown, so they render nicely.

R=
CC=
https://codereview.appspot.com/6939067

https://codereview.appspot.com/6939067/

[Gary Poster (gary)]

Please take a look.

https://codereview.appspot.com/6939067/

[Gary Poster (gary)]

self-reviewing change to .md file extension, per charm store

https://codereview.appspot.com/6939067/

[Gary Poster (gary)]

*** Submitted:

Move markdown files to .md extension

The charm store needs the document file names to end with .md in order
to process them as markdown.

R=
CC=
https://codereview.appspot.com/6939067

https://codereview.appspot.com/6939067/

=== modified file 'HACKING.txt'
--- HACKING.txt	2012-12-14 18:04:18 +0000
+++ HACKING.txt	2012-12-17 19:53:28 +0000
@@ -1,34 +1,26 @@
-==========================
-Juju GUI Charm Development
-==========================
+# Juju GUI Charm Development #
 
-Contacting the Developers
-=========================
+## Contacting the Developers ##
 
 Hi.  Thanks for looking at the charm.  If you are interested in helping us
 develop, we'd love to hear from you.  Our developer-oriented discussions
 happen on freenode's IRC network in the #juju-gui channel, and you can also
-join `the GUI developers mailing list
-<https://lists.ubuntu.com/mailman/listinfo/juju-gui>`_.
-
-
-Getting Started
-===============
+join [the GUI developers mailing list](https://lists.ubuntu.com/mailman/listinfo/juju-gui).
+
+
+## Getting Started ##
 
 First, you need a configured Juju environment: see the Juju docs about
-`getting started <https://juju.ubuntu.com/docs/getting-started.html>`_. If you
+[getting started](https://juju.ubuntu.com/docs/getting-started.html). If you
 do not yet have an environment defined, the Jitsu command "setup-environment"
 is an easy way to get started.
 
 You'll also need some dependencies and developer basics.
 
-::
-
-  sudo apt-get install bzr autoconf libtool python-charmhelpers
+    sudo apt-get install bzr autoconf libtool python-charmhelpers
 
 Next, you need the bzr branch.  We work from
-`lp:~juju-gui/charms/precise/juju-gui/trunk
-<https://code.launchpad.net/~juju-gui/charms/precise/juju-gui/trunk>`_.
+[lp:~juju-gui/charms/precise/juju-gui/trunk](https://code.launchpad.net/~juju-gui/charms/precise/juju-gui/trunk).
 
 You could start hacking now, but there's a bit more to do to prepare for
 running and writing tests.
@@ -36,7 +28,7 @@
 We use the Jitsu test command to run our functional tests.  At the time of
 this writing it is not yet released.  To run it you must first install it
 locally.  The files may be installed globally, or into your home directory (as
-here)::
+here):
 
     sudo apt-get install autoconf libtool python-charmhelpers
     bzr branch lp:~jimbaker/juju-jitsu/unit-test jitsu-unit-test
@@ -48,25 +40,23 @@
 
 The current incarnation of the Jitsu test command requires that the current
 directory name match the charm name, so you must check out the charm into a
-directory named "juju-gui"::
+directory named "juju-gui":
 
     bzr branch lp:~juju-gui/charms/precise/juju-gui/trunk juju-gui
 
 The branch directory must be placed (or linked from) within a local charm
 repository. It consists of a directory, itself containing a number of
-directories, one for each distribution codename, e.g. ``precise``. In turn, the
+directories, one for each distribution codename, e.g. `precise`. In turn, the
 codename directories will contain the charm repositories.
 
 Now you are ready to run the functional tests (see the next section).
 
-Testing
-=======
+## Testing ##
 
 There are two types of tests for the charm: unit tests and functional tests.
 
 
-Unit Tests
-----------
+### Unit Tests ###
 
 The unit tests do not require a functional Juju environment, and can be run
 with this command::
@@ -77,11 +67,10 @@
 customary way (i.e., "test_*.py").
 
 
-Functional Tests
-----------------
+### Functional Tests ###
 
 Running the functional tests requires a Juju testing environment as provided
-by the Jitsu test command (see `Getting Started`_, above).  All files in the
+by the Jitsu test command (see "Getting Started", above).  All files in the
 tests directory which end with ".test" will be run in a Juju Jitsu test
 environment.
 
@@ -92,10 +81,9 @@
         --logdir /tmp --timeout 40m
 
 This command will bootstrap the default Juju environment specified in your
-``~/.juju/environments.yaml``.
+`~/.juju/environments.yaml`.
 
-LXC
-~~~
+#### LXC ####
 
 Unfortunately, we have not found LXC-based Juju environments to be reliable
 for these tests.  At this time, we recommend using other environments, such as
@@ -105,12 +93,10 @@
 
 Currently running tests on a local environment is quite slow (with quantal
 host and precise container at least), so you may want to further increase the
-``jitsu test`` command timeout.
+`jitsu test` command timeout.
 
 If Jitsu generates errors about not being able to bootstrap...
 
-::
-
     CalledProcessError: Command '['juju', 'bootstrap']'...
 
 ...or if it hangs, then you may need to bootstrap the environment yourself and

=== modified file 'README.txt'
--- README.txt	2012-12-14 18:04:18 +0000
+++ README.txt	2012-12-17 19:53:28 +0000
@@ -1,12 +1,9 @@
-==============
-Juju GUI Charm
-==============
+# Juju GUI Charm #
 
 This charm makes it easy to deploy a Juju GUI into an existing environment.
 
 
-Warning
-=======
+## Warning ##
 
 The GUI and charm have two important limitations that we are actively working
 on.  We plan to publicly announce this charm once these limitations are
@@ -23,51 +20,46 @@
 this.
 
 
-Deploying the Juju GUI
-======================
+## Deploying the Juju GUI ##
 
 Deploying the Juju GUI is accomplished using Juju itself.
 
 You need a configured and bootstrapped Juju environment: see the Juju docs
-about `getting started <https://juju.ubuntu.com/docs/getting-started.html>`_,
+about [getting started](https://juju.ubuntu.com/docs/getting-started.html),
 and then run the usual bootstrap command.
 
-::
-
-  $ juju bootstrap
-
-Next, you simply need to deploy the charm and expose it.  (See also `Deploying
-with Jitsu`_ below, for another option.)
-
-::
-
-  $ juju deploy cs:~juju-gui/precise/juju-gui
-  $ juju expose juju-gui
+    $ juju bootstrap
+
+Next, you simply need to deploy the charm and expose it.  (See also "Deploying
+with Jitsu" below, for another option.)
+
+    $ juju deploy cs:~juju-gui/precise/juju-gui
+    $ juju expose juju-gui
 
 Finally, you need to identify the GUI's URL--sadly, the most annoying part of
 the process at the moment.  Right now (see the warning section above about not
 yet working with GUI releases) it can take an excessive amount of time for the
 GUI to be built and to start--20 minutes or more.  This command will let you
-see when it is ready to go by giving you regular status updates::
+see when it is ready to go by giving you regular status updates:
 
-  $ watch juju status
+    $ watch juju status
 
 Eventually, after many minutes, at the end of the status you will hopefully see
-something that looks like this::
+something that looks like this:
 
-  services:
-    juju-gui:
-      charm: cs:~juju-gui/precise/juju-gui-7
-      exposed: true
-      relations: {}
-      units:
-        juju-gui/0:
-          agent-state: started
-          machine: 1
-          open-ports:
-          - 80/tcp
-          - 8080/tcp
-          public-address: ec2-204-236-250-8.compute-1.amazonaws.com
+    services:
+      juju-gui:
+        charm: cs:~juju-gui/precise/juju-gui-7
+        exposed: true
+        relations: {}
+        units:
+          juju-gui/0:
+            agent-state: started
+            machine: 1
+            open-ports:
+            - 80/tcp
+            - 8080/tcp
+            public-address: ec2-204-236-250-8.compute-1.amazonaws.com
 
 That tells me I can go to the public-address in my browser
 (http://ec2-204-236-250-8.compute-1.amazonaws.com/ in this example), and start
@@ -79,8 +71,7 @@
 be prepared for unpleasant surprises like this.
 
 
-Deploying with Jitsu
---------------------
+### Deploying with Jitsu ###
 
 The instructions above cause you to use a separate machine to work with the
 GUI.  If you'd like to reduce your machine footprint (and perhaps your costs),
@@ -90,20 +81,17 @@
 
 For now, though, install Jitsu...
 
-::
-
-  $ sudo apt-get install juju-jitsu
+    $ sudo apt-get install juju-jitsu
 
 ...and then replace "juju deploy cs:~juju-gui/precise/juju-gui" from the
-previous instructions with this::
-
-  $ jitsu deploy-to 0 cs:~juju-gui/precise/juju-gui
-
-Contacting the Developers
-=========================
+previous instructions with this:
+
+    $ jitsu deploy-to 0 cs:~juju-gui/precise/juju-gui
+
+## Contacting the Developers ##
 
 If you run into problems with the charm, please feel free to contact us on the
-`Juju mailing list <https://lists.ubuntu.com/mailman/listinfo/juju>`_, or on
+[Juju mailing list](https://lists.ubuntu.com/mailman/listinfo/juju), or on
 freenode's IRC network on #juju.  We're not always around (working hours in
 Europe and NA are your best bets), but if you send us a mail or ping "jujugui"
 we will eventually get back to you.