Merge lp:~teknico/juju-gui/1086512-revise-docs into lp:juju-gui/experimental

[Nicola Larosa]

Put deploy docs in README, add HACKING.

Move the development instructions from the README file to a newly created HACKING one, update them, link the HACKING into the docs. Put deploying instructions in the README file. Revise all docs updating them, and fixing markup and links.

https://codereview.appspot.com/6924047/

[Nicola Larosa (teknico)]

Reviewers: mp+139226_code.launchpad.net,

Message:
Please take a look.

Description:
Put deploy docs in README, add HACKING.

Move the development instructions from the README file to a newly
created HACKING one, update them, link the HACKING into the docs. Put
deploying instructions in the README file. Revise all docs updating
them, and fixing markup and links.

https://code.launchpad.net/~teknico/juju-gui/1086512-revise-docs/+merge/139226

(do not edit description out of merge proposal)

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

Affected files:
   A HACKING
   M README
   A [revision details]
   M docs/architecture.rst
   M docs/d3-component-framework.rst
   M docs/index.rst
   M docs/process.rst
   M docs/style-guide.rst

[Francesco Banconi (frankban)]

Land as is.

Thanks Nicola, this branch looks good.

https://codereview.appspot.com/6924047/

[Gary Poster (gary)]

Land with changes

Hi Nicola. Thank you for this branch. It has many improvements.

Please either accept my suggested changes (which I'd prefer ;-) ) or let
me know why you don't want to.

Thanks

Gary

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

https://codereview.appspot.com/6924047/diff/1/HACKING#newcode67
HACKING:67: the container, and is launched using whichever branch you're
using.
...and it is launched...

https://codereview.appspot.com/6924047/diff/1/HACKING#newcode94
HACKING:94: After which, the gui should be functional (it automatically
polls the
After this, the gui...

https://codereview.appspot.com/6924047/diff/1/docs/d3-component-framework.rst
File docs/d3-component-framework.rst (right):

https://codereview.appspot.com/6924047/diff/1/docs/d3-component-framework.rst#newcode2
docs/d3-component-framework.rst:2: D3 component framework
English rules are usually to capitalize the words of titles, as long as
they are not articles or prepositions. Why did you change that here?
It's not particularly important, but I don't like to see things that
seem to me to be steps backwards. I suggest reverting the three title
capitalization changes in this file.

https://codereview.appspot.com/6924047/diff/1/docs/d3-component-framework.rst#newcode25
docs/d3-component-framework.rst:25: Module writers guide
Revert capitalization change, as discussed above.

https://codereview.appspot.com/6924047/diff/1/docs/d3-component-framework.rst#newcode231
docs/d3-component-framework.rst:231: Complete example
revert, per above discussion.

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

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode2
docs/process.rst:2: Process notes
Revert: It was standard English title style before

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode5
docs/process.rst:5: Checklist for starting a branch
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode21
docs/process.rst:21: Checklist for preparing for a review
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode63
docs/process.rst:63: Checklist for reviewing
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode95
docs/process.rst:95: Checklist for making a stable release
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode148
docs/process.rst:148: Checklist for making a developer release
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode205
docs/process.rst:205: Checklist for running a daily meeting
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode246
docs/process.rst:246: Checklist for running a weekly retrospective
revert

https://codereview.appspot.com/6924047/diff/1/docs/process.rst#newcode303
docs/process.rst:303: Slack project policy
revert

https://codereview.appspot.com/6924047/diff/1/docs/style-guide.rst
File docs/style-guide.rst (right):

https://codereview.appspot.com/6924047/diff/1/docs/style-guide.rst#newcode2
docs/style-guide.rst:2: Style guide
revert

https://codereview.appspot.com/6924047/

[Nicola Larosa (teknico)]

gary.poster wrote:
> Please either accept my suggested changes (which I'd prefer ;-) ) or
let me know
> why you don't want to.

Gary, I will apply your changes.

https://codereview.appspot.com/6924047/diff/1/docs/d3-component-framework.rst#newcode2
> docs/d3-component-framework.rst:2: D3 component framework
> English rules are usually to capitalize the words of titles, as long
as they are
> not articles or prepositions. Why did you change that here?

There is a mismatch in title style between the README and Style Guide
files, that do not capitalize them, and the D3 Component Framework and
Process Notes, that do. It becomes apparent when you look at the index
in the generated pages.

Being not very well versed with formal English rules, I felt
capitalization as unusual and kind of "heavy", so decided to remove it.
Since you prefer abiding to those rules I'll revert the changes, and
apply capitalization to the former files too.

https://codereview.appspot.com/6924047/

[lp:~teknico/juju-gui/1086512-revise-docs]

279. By Nicola Larosa on 2012-12-12

Merged from trunk.

280. By Nicola Larosa on 2012-12-12

Revert capitalization changes, make new capitalization changes, add 'sphinx' target to Makefile.

[Nicola Larosa (teknico)]

*** Submitted:

Put deploy docs in README, add HACKING.

Move the development instructions from the README file to a newly
created HACKING one, update them, link the HACKING into the docs. Put
deploying instructions in the README file. Revise all docs updating
them, and fixing markup and links.

R=frankban, gary.poster
CC=
https://codereview.appspot.com/6924047

https://codereview.appspot.com/6924047/

=== added file 'HACKING'
--- HACKING	1970-01-01 00:00:00 +0000
+++ HACKING	2012-12-12 10:07:21 +0000
@@ -0,0 +1,197 @@
+===========
+Development
+===========
+
+Here is how to develop on this codebase.
+
+Developer Install
+=================
+
+Juju GUI uses nodejs based development tools.
+
+You'll need nodejs & npm from the ppa::
+
+  $ sudo add-apt-repository ppa:chris-lea/node.js
+  $ sudo apt-get update
+  $ sudo apt-get install nodejs npm
+
+You also need ImageMagick::
+
+  $ sudo apt-get install imagemagick
+
+The linter will be installed locally per branch, but if you want editor
+integration, you may want to install jshint globally in your system::
+
+  $ sudo npm install -g jshint
+
+For building the docs, you also need sphinx::
+
+  $ sudo apt-get install python-sphinx
+
+To make releases, you'll need pytz::
+
+  $ sudo apt-get install python-tz
+
+The gui frontend can be installed with::
+
+  $ bzr branch lp:juju-ui trunk
+  $ cd trunk
+  $ make server
+
+It may take a while for the server to start the first time as npm will
+need to download packages.  When ready, the server will print:
+
+Server listening on 8888
+
+You can then access the GUI at <http://localhost:8888/>.
+
+You'll also need to deploy a juju environment with REST api access.
+Currently that work resides in a pipeline of juju branches. The
+recommended branch to use as a server is ``lp:~hazmat/juju/rapi-rollup``.
+
+You can use it with any environment, but for dev purposes, a local
+environment works well. One environment option specific to this branch
+is the api-port. An appropriate sample configuration::
+
+  default: dev
+  environments:
+    dev:
+      type: local
+      data-dir: /home/kapil/.juju/local
+      admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4
+      default-series: precise
+      juju-origin: ppa
+      api-port: 8081
+
+Note that juju-origin is set to the ppa, the api server runs outside of
+the container, and is launched using whichever branch you're using.
+
+Also note that the api-port should be set at 8081, which the gui's
+initial environment connection currently defaults to.
+
+You'll need to bootstrap the local environment, and deploy one service.
+The api server needs access to the provisioning credentials which are
+lazily initialized in juju upon usage.
+
+Juju-gui and rapi-rollup can communicate via an encrypted WebSockets
+connection: to enable it, add the following line to the config above::
+
+  api-secure: true
+
+You will also need to edit your ``app/config.js`` replacing
+``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.
+
+By default, rapi-rollup uses a self-signed certificate; because of that you
+will need to visit the <https://localhost:8081/ws> WebSockets URL with your
+browser and accept the included self-signed certificate, or the WebSockets
+encrypted connection will not work.
+
+In order to use a different certificate, you add an api-keys option to the
+config above: its value will be the path of the directory containing the
+certificate and the private key, whose filenames will have to be respectively
+``juju.crt`` and ``juju.key``.
+
+After which, the gui should be functional (it automatically polls the
+api server for establishing a websocket).
+
+Running Unit Tests
+==================
+
+  $ make test
+
+Running Lint
+============
+
+  $ make lint
+
+API Documentation
+=================
+
+Generated JavaScript documentation is available in the yuidoc directory after
+running the command ``make yuidoc``. You can view the docs by running::
+
+  $ xdg-open yuidoc/index.html
+
+The `documentation <http://yui.github.com/yuidoc/syntax/>`_ for YUIDoc markup
+is available.
+
+Project Documentation
+=====================
+
+The project documentation is available in the ``docs/`` directory. It needs
+Sphinx::
+
+  $ sudo apt-get install python-sphinx
+
+Build the documentation::
+
+  $ make doc
+
+(This will also generate the above mentioned yuidoc documentation.)
+
+View it::
+
+  $ xdg-open docs/_build/html/index.html
+
+Making Releases
+===============
+
+To make a release, you must either be in a checkout of lp:juju-gui
+without uncommitted changes, or you must override one of the
+`pertinent variable names`_ to force a release.
+
+.. _`pertinent variable names`: `Potentially Useful Release-Oriented Makefile Variables`_
+
+You also need to have a gpg key, and the python-pytz package installed (as
+well as launchpadlib, but that is installed by default in Ubuntu).
+
+See the Process document (docs/process.rst) for step-by-step checklists to
+make developer and stable releases.
+
+Potentially Useful Release-Oriented Makefile Variables
+------------------------------------------------------
+
+The following is a list of pertinent Makefile variables.
+
+FINAL
+  Set FINAL to any non-empty value to make a final release. This will cause
+  the bzr revno to be omitted from the tarball name, and (if you use the
+  release target) will cause the release to be uploaded to the stable series
+  rather than the trunk series. Example usage::
+
+    $ FINAL=1 make release
+
+PROD
+  By default, releases will be uploaded to staging.launchpad.net, which is a
+  separate version of Launchpad that uses a temporary database.  This can be
+  convenient for trying out the release process in the Makefile without
+  affecting our actual production releases.  Set PROD to any non-empty value
+  to send uploads to launchpad.net, the production version of Launchpad, when
+  you are ready to make a real release.
+
+  Note that you may need to ask the webops to turn off the two-factor
+  authentication on your Launchpad staging account in order for the staging to
+  work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
+  something like "webops, could you disable 2FA on my staging account?"
+
+  Example usage::
+
+    $ PROD=1 make release
+
+IS_TRUNK_CHECKOUT
+  Set this to any non-empty value to force the Makefile to believe it is
+  working with a trunk checkout. Example usage::
+
+    $ IS_TRUNK_CHECKOUT=1 make release
+
+HAS_NO_CHANGES
+  Set this to any non-empty value to force the Makefile to believe that the
+  current code tree has no changes. Example usage::
+
+    $ HAS_NO_CHANGES=1 make release
+
+IS_SAFE_RELEASE
+  Set this to any non-empty value to force the Makefile to bypass checks of
+  IS_TRUNK_CHECKOUT and HAS_NO_CHANGES. Example usage::
+
+    $ IS_SAFE_RELEASE=1 make release
 
=== modified file 'Makefile'
--- Makefile	2012-12-11 15:54:02 +0000
+++ Makefile	2012-12-12 10:07:21 +0000
@@ -128,10 +128,12 @@
 yuidoc/index.html: node_modules/yuidocjs $(JSFILES)
 	node_modules/.bin/yuidoc -o yuidoc -x assets app
 
+sphinx:
+	make -C docs html
+
 yuidoc: yuidoc/index.html
 
-doc: yuidoc
-	make -C docs html
+doc: sphinx yuidoc
 
 $(SPRITE_GENERATED_FILES): node_modules/grunt node_modules/node-spritesheet \
 		$(SPRITE_SOURCE_FILES)
 
=== modified file 'README'
--- README	2012-12-10 14:20:35 +0000
+++ README	2012-12-12 10:07:21 +0000
@@ -1,197 +1,37 @@
-======
-README
-======
-
-Developer Install
-=================
-
-Juju GUI uses nodejs based development tools.
-
-You'll need nodejs & npm from the ppa::
-
-  $ sudo add-apt-repository ppa:chris-lea/node.js
-  $ sudo apt-get update
-  $ sudo apt-get install nodejs npm
-
-You also need ImageMagick::
-
-  $ sudo apt-get install imagemagick
-
-The linter will be installed locally per branch, but if you want editor
-integration, you may want to install jshint globally in your system::
-
-  $ sudo npm install -g jshint
-
-For building the docs, you also need sphinx::
-
-  $ sudo apt-get install python-sphinx
-
-To make releases, you'll need pytz::
-
-  $ sudo apt-get install python-tz
-
-The gui frontend can be installed with::
-
-  $ bzr branch lp:juju-ui trunk
-  $ cd trunk
-  $ make server
-
-It may take a while for the server to start the first time as npm will
-need to download packages.  When ready, the server will print:
-
-Server listening on 8888
-
-You can then access the GUI at http://localhost:8888
-
-You'll also need to deploy a juju environment with REST api access.
-Currently that work resides in a pipeline of juju branches. The
-recommended branch to use as a server is ``lp:~hazmat/juju/rapi-delta``.
-
-You can use it with any environment, but for dev purposes, a local
-environment works well. One environment option specific to this branch
-is the api-port. An appropriate sample configuration::
-
-  default: dev
-  environments:
-    dev:
-      type: local
-      data-dir: /home/kapil/.juju/local
-      admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4
-      default-series: precise
-      juju-origin: ppa
-      api-port: 8081
-
-Note that juju-origin is set to the ppa, the api server runs outside of
-the container, and is launched using whichever branch you're using.
-
-Also note that the api-port should be set at 8081, which the gui's
-initial environment connection currently defaults to.
-
-You'll need to bootstrap the local environment, and deploy one service.
-The api server needs access to the provisioning credentials which are
-lazily initialized in juju upon usage.
-
-Juju-gui and rapi-delta can communicate via an encrypted WebSockets
-connection: to enable it, add the following line to the config above::
-
-  api-secure: true
-
-You will also need to edit your ``app/config.js`` replacing
-``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.
-
-By default, rapi-delta uses a self-signed certificate; because of that you
-will need to visit the https://localhost:8081/ws WebSockets URL with your
-browser and accept the included self-signed certificate, or the WebSockets
-encrypted connection will not work.
-
-In order to use a different certificate, you add an api-keys option to the
-config above: its value will be the path of the directory containing the
-certificate and the private key, whose filenames will have to be respectively
-``juju.crt`` and ``juju.key``.
-
-After which, the gui should be functional (it automatically polls the
-api server for establishing a websocket).
-
-Running unit tests
-==================
-
-  $ xdg-open test/index.html
-
-Documentation
-=============
-
-Generated JavaScript documentation is available in the yuidoc directory.
-Start with the index.html file. You can view the docs by running::
-
-  $ xdg-open yuidoc/index.html
-
-To regenerate the docs run::
-
-  $ make yuidoc
-
-The documentation for YUIDoc markup is at
-http://yui.github.com/yuidoc/syntax/ .
-
-Running lint
-============
-
-  $ jshint --config=jshint.config `bzr ls -RV -k file | grep -v assets/`
-
-Making releases
-===============
-
-To make a release, you must either be in a checkout of lp:juju-gui
-without uncommitted changes, or you must override one of the
-`pertinent variable names`_ to force a release.
-
-.. _`pertinent variable names`: `Potentially Useful Release-Oriented Makefile Variables`_
-
-You also need to have a gpg key, and the python-pytz package installed (as
-well as launchpadlib, but that is installed by default in Ubuntu).
-
-See the Process document (docs/process.rst) for step-by-step checklists to
-make developer and stable releases.
-
-Potentially Useful Release-Oriented Makefile Variables
-------------------------------------------------------
-
-The following is a list of pertinent Makefile variables.
-
-FINAL
-  Set FINAL to any non-empty value to make a final release. This will cause
-  the bzr revno to be omitted from the tarball name, and (if you use the
-  release target) will cause the release to be uploaded to the stable series
-  rather than the trunk series. Example usage::
-
-    $ FINAL=1 make release
-
-PROD
-  By default, releases will be uploaded to staging.launchpad.net, which is a
-  separate version of Launchpad that uses a temporary database.  This can be
-  convenient for trying out the release process in the Makefile without
-  affecting our actual production releases.  Set PROD to any non-empty value
-  to send uploads to launchpad.net, the production version of Launchpad, when
-  you are ready to make a real release.
-
-  Note that you may need to ask the webops to turn off the two-factor
-  authentication on your Launchpad staging account in order for the staging to
-  work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
-  something like "webops, could you disable 2FA on my staging account?"
-
-  Example usage::
-
-    $ PROD=1 make release
-
-IS_TRUNK_CHECKOUT
-  Set this to any non-empty value to force the Makefile to believe it is
-  working with a trunk checkout. Example usage::
-
-    $ IS_TRUNK_CHECKOUT=1 make release
-
-HAS_NO_CHANGES
-  Set this to any non-empty value to force the Makefile to believe that the
-  current code tree has no changes. Example usage::
-
-    $ HAS_NO_CHANGES=1 make release
-
-IS_SAFE_RELEASE
-  Set this to any non-empty value to force the Makefile to bypass checks of
-  IS_TRUNK_CHECKOUT and HAS_NO_CHANGES. Example usage::
-
-    $ IS_SAFE_RELEASE=1 make release
-
-More documentation
-==================
-
-Install Sphinx::
-
-  $ sudo apt-get install python-sphinx
-
-Build the docs::
-
-  $ cd docs
-  $ make html
-
-View them::
-
-  $ xdg-open _build/html/index.html
+========
+Juju-GUI
+========
+
+Welcome. Juju-GUI is a web-based GUI for `Juju <https://juju.ubuntu.com/>`_.
+Juju lets you deploy connected services to the cloud in a convenient,
+vendor-neutral, and powerful way. The GUI lets you visualize and manage
+your work more intuitively from a web browser.
+
+See also:
+
+- `The new Juju GUI: because a picture paints a thousand words
+  <http://blog.canonical.com/2012/10/29/the-new-juju-gui-because-a-picture-paints-a-thousand-words/>`_
+- a `demo of trunk <http://uistage.jujucharms.com:8080/>`_, which is reset
+  every 15 minutes.
+
+Deploy
+======
+
+There are no official releases of Juju-GUI yet, so you have to get the source
+code from Launchpad::
+
+  $ bzr branch lp:juju-gui
+
+The most useful available commands are shown by the command::
+
+  $ make help
+
+You'll typically want to run one of ``make prod``,  ``make debug`` or ``make
+devel`` to deploy an environment. You might also run ``make test`` to check
+that everything is ok. You may also run ``make doc`` to generate the available
+documentation.
+
+Configure
+=========
+
+TBD
 
=== modified file 'docs/architecture.rst'
--- docs/architecture.rst	2012-10-05 09:42:27 +0000
+++ docs/architecture.rst	2012-12-12 10:07:21 +0000
@@ -6,55 +6,54 @@
 ========
 
 MVC YUI
-~~~~~~~
+-------
 
-Juju-gui is based on yui's backbone style app framework. The official docs
-for this are highly recommended for developers:
-http://yuilibrary.com/yui/docs/app/
+Juju-gui is based on yui's backbone style app framework. The `official docs
+<http://yuilibrary.com/yui/docs/app/>`_ are highly recommended for developers.
 
 An overview of the individual pieces.
 
-- Router - Route dispatch by url, saves and restores url state.
-  http://yuilibrary.com/yui/docs/router/
-
-- Views - Rendering of a view
-  http://yuilibrary.com/yui/docs/view/index.html
-
-- Model - Domain objects with change events
-  http://yuilibrary.com/yui/docs/model/
-  http://yuilibrary.com/yui/docs/model-list/
+- `Router <http://yuilibrary.com/yui/docs/router/>`_ - Route dispatch by url,
+  saves and restores url state.
+
+- `Views <http://yuilibrary.com/yui/docs/view/index.html>`_ - Rendering of a
+  view.
+
+- `Model <http://yuilibrary.com/yui/docs/model/>`_,
+  `ModelList <http://yuilibrary.com/yui/docs/model-list/>`_ - Domain objects
+  with change events.
 
 Environment Integration
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 The gui connects and communicates to the environment over a web socket
 connection.
 
 RPC Calls
-~~~~~~~~~
+---------
 
 Completion callbacks can be used with any of the methods on the environment.
 Multiple calls are done in parallel.
 
 RPC Events
-~~~~~~~~~~
+----------
 
 Messages from the backend for known rpc operation results are messaged out as
 Environment events.
 
 Delta Stream
-~~~~~~~~~~~~
+------------
 
 A stream of object changes, used to update models.
 
 Scenarios
----------
+~~~~~~~~~
 
 - new client
 - existing client disconnects and reconnects
 
 Requirements
-------------
+~~~~~~~~~~~~
 
 ::
 
@@ -67,14 +66,14 @@
   -- delta
 
 Questions
-~~~~~~~~~
-
-Model Composition and relations.
-
-relations by id
-
-We have multiple object states for a given.
-
-Inline combo handler for yui: https://github.com/rgrove/combohandler
-
-More complicated but similiar: https://github.com/jafl/YUI-3-Stockpile
+---------
+
+- Model Composition and relations.
+
+- relations by id
+
+- We have multiple object states for a given.
+
+- Inline combo handler for YUI: <https://github.com/rgrove/combohandler>.
+
+- More complicated but similiar: <https://github.com/jafl/YUI-3-Stockpile>.
 
=== modified file 'docs/d3-component-framework.rst'
--- docs/d3-component-framework.rst	2012-11-29 03:54:35 +0000
+++ docs/d3-component-framework.rst	2012-12-12 10:07:21 +0000
@@ -15,7 +15,7 @@
 explain this usage as it exists today.
 
 The framework only models two high level objects, Component and Module. A
-Component is a top level container around Module objects. The Component 
+Component is a top level container around Module objects. The Component
 provides the implementation of the declarative behavior provided by the
 framework. The Module(s) implement the logical sections of the application. In
 the YUI world it might be common to expect each Module to be the application's
@@ -76,14 +76,14 @@
 this point that any d3js synthetic events are bound to the canvas (see the
 section on events below). This separation of phases exists to make the life of
 the Module writer simpler. They can rely on whatever elements they'll be drawing
- (adding children to an svg object for example) will already have its container 
- properly available due to the renderOnce setup. They can also be sure that 
- any ``update`` driven intermediate data will be computed and available for
- use in ``render``. This reduces the need for checks in each module to assert
- the most basic DOM state.
+(adding children to an svg object for example) will already have its container
+properly available due to the renderOnce setup. They can also be sure that
+any ``update`` driven intermediate data will be computed and available for
+use in ``render``. This reduces the need for checks in each module to assert
+the most basic DOM state.
 
-After the initial render its expected that updates to the scene occur via the 
-event handlers in the various modules. Render will not usually need to be called 
+After the initial render its expected that updates to the scene occur via the
+event handlers in the various modules. Render will not usually need to be called
 more than once unless the entire Component rendering is removed from the DOM and
 then later re-attached.
 
 
=== added symlink 'docs/hacking.rst'
=== target is u'../HACKING'
=== modified file 'docs/index.rst'
--- docs/index.rst	2012-11-28 12:30:32 +0000
+++ docs/index.rst	2012-12-12 10:07:21 +0000
@@ -13,6 +13,7 @@
    :maxdepth: 2
 
    readme
+   hacking
    style-guide
    architecture
    d3-component-framework
 
=== modified file 'docs/process.rst'
--- docs/process.rst	2012-12-10 14:20:35 +0000
+++ docs/process.rst	2012-12-12 10:07:21 +0000
@@ -6,9 +6,9 @@
 ===============================
 
 - Understand the problem.  If you don't, ask and be persistent until you do.
-- When determining a solution, consider this preferred Software
-  Architecture Cheat Sheet:
-  http://gorban.org/post/32873465932/software-architecture-cheat-sheet
+- When determining a solution, consider this preferred `Software
+  Architecture Cheat Sheet
+  <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_
 - Have a pre-implementation call with someone about your solution.  If you
   are not sure of your solution, prototype before the pre-implementation call.
 - Use TDD.  Your prototype might be perfect, but you can still move it aside
@@ -16,7 +16,7 @@
 - Update the CHANGES.yaml file with your changes.  The newest (topmost)
   section should have the version "unreleased".  If not and you are
   making changes, add an "unreleased" section at the top.  All other
-  version numbers follow Semantic Versioning (http://semver.org/).
+  version numbers follow `Semantic Versioning <http://semver.org/>`_.
 
 Checklist for Preparing for a Review
 ====================================
@@ -79,8 +79,8 @@
   * Make sure that new code has tests.
   * Make sure you can understand the new code.  Ask for clarification if
     necessary.
-  * Consider the advice in this preferred Software Architecture Cheat Sheet.
-    http://gorban.org/post/32873465932/software-architecture-cheat-sheet
+  * Consider the advice in this preferred `Software Architecture Cheat Sheet
+    <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_
   * Make sure changes to a file correspond to the naming conventions and other
     stylistic considerations local to that file, and within our project.
   * Before you ask for a change, think and make sure you can't compromise
 
=== modified file 'docs/style-guide.rst'
--- docs/style-guide.rst	2012-11-07 18:41:11 +0000
+++ docs/style-guide.rst	2012-12-12 10:07:21 +0000
@@ -15,7 +15,7 @@
 indention will be applied.
 
 
-For loops
+For Loops
 =========
 
 Unless you are counting something, for loops (and for-in loops) are a trap.
@@ -29,7 +29,7 @@
 should end with a non-blank line).
 
 
-Object literal formatting
+Object Literal Formatting
 =========================
 
 Things you should do:
@@ -66,7 +66,7 @@
         errors = utils.validate(values, schema);
 
 
-Chaining method calls
+Chaining Method Calls
 =====================
 
 Some APIs are designed such that mutating method calls return the object being
@@ -160,13 +160,13 @@
 ========
 
 We use YUIDoc to document the applications internals.  YUIDoc comments
-start with "/**" and end with "*/".  The Makefile includes a simple
+start with ``/**`` and end with ``*/``.  The Makefile includes a simple
 linter that enforces YUIDoc comments for each function in the
 application.
 
 This simple linting sometimes means that functions that we might not
 otherwise document require documentation.  If a one-line comment is
-sufficient in those situations, a comment of this form may be used:
+sufficient in those situations, a comment of this form may be used::
 
     /** Handle errors */
     error_callback: function(err) {
@@ -174,7 +174,7 @@
     }
 
 Most functions (or methods) will call for normal, multi-line YUIDoc
-comments like this:
+comments like this::
 
     /**
      * Frob the thingy.
@@ -184,5 +184,5 @@
      * @return {undefined} Side-effects only, eturns nothing.
      */
 
-Full documentation for the various YUIDoc directives is at
-http://yui.github.com/yuidoc/syntax/ .
+`Full documentation <http://yui.github.com/yuidoc/syntax/>`_
+for the various YUIDoc directives is available.