Improve contributor documentation

Fix various errors in the contributor documentation:

- Factual mistakes (wrong file locations, etc)
- Formatting errors
- Typos

Change-Id: I4863ca10a532ac74491cfb19f8382e3d5287d2f3

README.rst

@@ -74,7 +74,7 @@ Development
 For development, start with the getting started instructions above.
 Once you have a working virtualenv and all the necessary packages, read on.
 
-If dependencies are added to either ``horizon`` or ``openstack-dashboard``,
+If dependencies are added to either ``horizon`` or ``openstack_dashboard``,
 they should be added to ``requirements.txt``.
 
 The ``run_tests.sh`` script invokes tests and analyses on both of these

doc/source/contributing.rst

@@ -11,7 +11,10 @@ Before you dive into writing patches, here are some of the basics:
 * Bug tracker: https://bugs.launchpad.net/horizon
 * Source code: https://github.com/openstack/horizon
 * Code review: https://review.openstack.org/#q,status:open+project:openstack/horizon,n,z
-* Jenkins build status: https://jenkins.openstack.org/view/Horizon/
+* Continuous integration:
+
+  * Jenkins: https://jenkins.openstack.org
+  * Zuul: http://status.openstack.org/zuul
 * IRC Channel: #openstack-horizon on Freenode.
 
 Making Contributions
@@ -47,12 +50,13 @@ plunging in head-first:
 
 * Report bugs, triage new tickets, and review old tickets on
   the `bug tracker`_.
-* Propose ideas for improvements via Launchpad Blueprints, via the
+* Propose ideas for improvements via `Launchpad Blueprints`_, via the
   mailing list on the project page, or on IRC.
 * Write documentation!
 * Write unit tests for untested code!
 
 .. _`bug tracker`: https://bugs.launchpad.net/horizon
+.. _`Launchpad Blueprints`: https://blueprints.launchpad.net/horizon
 
 Choosing Issues To Work On
 --------------------------
@@ -165,7 +169,7 @@ so as to match both the JavaScript and HTML files.
 HTML
 ----
 
-Again, readability is paramount; however be conscientous of how the browser
+Again, readability is paramount; however be conscientious of how the browser
 will handle whitespace when rendering the output. Two spaces is the preferred
 indentation style to match all front-end code.
 

doc/source/quickstart.rst

@@ -5,7 +5,7 @@ Horizon Quickstart
 Setup
 =====
 
-To setup an Horizon development environment simply clone the Horizon git
+To setup a Horizon development environment simply clone the Horizon git
 repository from http://github.com/openstack/horizon and execute the
 ``run_tests.sh`` script from the root folder (see :doc:`ref/run_tests`)::
 
@@ -13,7 +13,7 @@ repository from http://github.com/openstack/horizon and execute the
     > cd horizon
     > ./run_tests.sh
 
-Next you will need to setup your Django application config by copying ``openstack_dashboard/local/local_settings.py.example`` to ``openstack_dashboard/local_settings.py``. To do this quickly you can use the following command::
+Next you will need to setup your Django application config by copying ``openstack_dashboard/local/local_settings.py.example`` to ``openstack_dashboard/local/local_settings.py``. To do this quickly you can use the following command::
 
     > cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py
 

doc/source/ref/run_tests.rst

@@ -18,10 +18,9 @@ you should do is to run ``./run_tests.sh`` from the root of the repository.
 This will do two things for you:
 
     #. Set up a virtual environment for both the ``horizon`` module and
-       the ``openstack-dashboard`` project using
+       the ``openstack_dashboard`` project using ``./tools/install_venv.py``.
-       ``openstack-dashboard/tools/install_venv.py``.
+    #. Run the tests for both ``horizon`` and ``openstack_dashboard`` using
-    #. Run the tests for both ``horizon`` and ``openstack-dashboard`` using
+       their respective environments and verify that everything is working.
-       their respective environments and verify that evreything is working.
 
 Setting up the environment the first time can take several minutes, but only
 needs to be done once. If dependencies are added in the future, updating the
@@ -80,7 +79,7 @@ dashboards and panels based on basic templates.
 Dashboards
 ----------
 
-To create a new dashboard, run the following:
+To create a new dashboard, run the following::
 
     ./run_tests.sh -m startdash <dash_name>
 
@@ -90,13 +89,13 @@ module with the basic dashboard code filled in, and various other common
 
 Available options:
 
-* --target: the directory in which the dashboard files should be created.
+* ``--target``: the directory in which the dashboard files should be created.
   Default: A new directory within the current directory.
 
 Panels
 ------
 
-To create a new panel, run the following:
+To create a new panel, run the following::
 
     ./run_tests -m startpanel <panel_name> --dashboard=<dashboard_path>
 
@@ -106,9 +105,9 @@ module with the basic panel code filled in, and various other common
 
 Available options:
 
-* -d, --dashboard: The dotted python path to your dashboard app (the module
+* ``-d``, ``--dashboard``: The dotted python path to your dashboard app (the module
   which containers the ``dashboard.py`` file.).
-* --target: the directory in which the panel files should be created.
+* ``--target``: the directory in which the panel files should be created.
   If the value is ``auto`` the panel will be created as a new directory inside
   the dashboard module's directory structure. Default: A new directory within
   the current directory.
@@ -166,7 +165,7 @@ the root of the repository with ``run_tests.sh`` like so::
 
 This is effectively just an alias for::
 
-    ./openstack-dashboard/tools/with_venv.sh ./openstack-dashboard/dashboard/manage.py runserver
+    ./tools/with_venv.sh ./manage.py runserver
 
 Generating the documentation
 ============================
@@ -181,11 +180,11 @@ Updating the translation files
 ==============================
 
 You can update all of the translation files for both the ``horizon`` app and
-``openstack_dashboard`` project with a single command:
+``openstack_dashboard`` project with a single command::
 
     ./run_tests.sh --makemessages
 
-or, more compactly:
+or, more compactly::
 
     ./run_tests.sh --m
 
@@ -215,7 +214,7 @@ Environment Backups
 
 To speed up the process of doing clean checkouts, running continuous
 integration tests, etc. there are options for backing up the current
-environment and restoring from a backup.
+environment and restoring from a backup::
 
     ./run_tests.sh --restore-environment
     ./run_tests.sh --backup-environment

doc/source/releases/2012_1.rst

@@ -21,7 +21,7 @@ goals for the Essex release cycle. Massive strides have been made to allow
 for the addition of new "plug-in" components and customization of OpenStack
 Dashboard deployments.
 
-To support this extensability, all the components used to build on Horizon's
+To support this extensibility, all the components used to build on Horizon's
 interface are now modular and reusable. Horizon's own dashboards use these
 components, and they have all been built with third-party developers in mind.
 Some of the main components are listed below.
@@ -49,10 +49,10 @@ Tabs and TabGroups
 
 Another extremely common user-interface element is the use of "tabs" to break
 down discrete groups of data into manageable chunks. Since these tabs often
-encompasse vastly different data, may have completely different access
+encompass vastly different data, may have completely different access
 restrictions, and may sometimes be better-off being loaded dynamically rather
 than with the initial page load, Horizon includes tab and tab group classes for
-constructing these interfaces elegently and with no knowledge of the HTML, CSS
+constructing these interfaces elegantly and with no knowledge of the HTML, CSS
 or JavaScript involved.
 
 Nova Features
@@ -75,7 +75,7 @@ Support for Nova's features has been greatly improved in Essex:
 Settings
 --------
 
-A new "Settings" area was added that offers several userful functions:
+A new "Settings" area was added that offers several useful functions:
 
 * EC2 credentials download.
 * OpenStack RC file download.
@@ -145,4 +145,4 @@ Backwards Compatibility
 The Essex Horizon release is only partially backwards-compatible with Diablo
 OpenStack components. While it is largely possible to log in and interact, many
 functions in Nova, Glance and Keystone changed too substantially in Essex to
-maintain full compatibliity.
+maintain full compatibility.

doc/source/releases/2013_1.rst

@@ -64,7 +64,7 @@ little to no information as to why.
 
 In Grizzly we have instead chosen to improve this by treating service API
 401 and 403 errors as slightly less severe than unauthorized access attempts
-to resitricted areas of Horizon. The reason for this is threefold:
+to restricted areas of Horizon. The reason for this is threefold:
 
 #. For a non-malicious user these errors are almost 100% the result of
    misconfiguration and this makes debugging possible.
@@ -120,7 +120,7 @@ involved. Moreover, the combined table-plus-form approach the OpenStack
 Dashboard had taken only made the UX more frustrating for an already difficult
 area.
 
-In Grizzly this has all been reworked to be signficantly simpler, and to
+In Grizzly this has all been reworked to be significantly simpler, and to
 provide as much contextual help and streamlining as possible.
 
 Icons!
@@ -200,7 +200,7 @@ Other Improvements and Fixes
 
 * Security groups can be added to a running instance.
 
-* Volume quotas are handled by the appopriate service depending on whether
+* Volume quotas are handled by the appropriate service depending on whether
   or not Cinder is enabled.
 
 * Password confirmation boxes are now validated for matching passwords on

doc/source/releases/2013_2.rst

@@ -59,7 +59,7 @@ continues to grow. New features in the Havana release include:
 
 * Editable default quotas.
 * The ability for an administrator to reset the password of a server/instance.
-* Availablity zone support.
+* Availability zone support.
 * Improved region support.
 * Instance resizing.
 * Improved boot-from-volume support.

doc/source/testing.rst

@@ -6,7 +6,7 @@ How to run the tests
 ====================
 
 Because Horizon is composed of both the ``horizon`` app and the
-``openstack-dashboard`` reference project, there are in fact two sets of unit
+``openstack_dashboard`` reference project, there are in fact two sets of unit
 tests. While they can be run individually without problem, there is an easier
 way:
 

doc/source/topics/customizing.rst

@@ -10,7 +10,7 @@ can be overwritten by adding the attribute ``SITE_BRANDING``
 to ``local_settings.py`` with the value being the desired name.
 
 The file ``local_settings.py`` can be found at the Horizon directory path of
-``horizon/openstack-dashboard/local/local_settings.py``.
+``openstack_dashboard/local/local_settings.py``.
 
 Changing the Logo
 =================
@@ -24,7 +24,7 @@ The OpenStack Logo is pulled in through ``style.css``::
         background: url(../images/logo.png) top left no-repeat;
 
 To override the OpenStack Logo image, replace the image at the directory path
-``horizon/openstack-dashboard/dashboard/static/dashboard/images/logo.png``.
+``openstack_dashboard/static/dashboard/img/logo.png``.
 
 The dimensions should be ``width: 108px, height: 121px``.
 
@@ -162,8 +162,8 @@ Custom Stylesheets
 ==================
 
 It is possible to define custom stylesheets for your dashboards. Horizon's base
-template ``horizon/templates/horizon/base.html`` defines multiple blocks that
+template ``horizon/templates/base.html`` defines multiple blocks that
-can be overriden.
+can be overridden.
 
 To define custom css files that apply only to a specific dashboard, create
 a base template in your dashboard's templates folder, which extends Horizon's

doc/source/topics/deployment.rst

@@ -147,7 +147,7 @@ Enabled by::
     SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
     DATABASES = {
         'default': {
-            # Databe configuration here
+            # Database configuration here
         }
     }
 
@@ -201,7 +201,7 @@ When implementing Horizon for public usage, with the website served through
 HTTPS, it is recommended that the following settings are applied.
 
 To help protect the session cookies from `cross-site scripting`_, add the
-following to ``local_settings.py`` :
+following to ``local_settings.py``::
 
     CSRF_COOKIE_SECURE = True
     SESSION_COOKIE_SECURE = True

doc/source/topics/policy.rst

@@ -45,7 +45,7 @@ the files listed in ``POLICY_FILES`` or all policy checks will pass.
 ``POLICY_FILES``
 ----------------
 
-Default: { 'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}
+Default: ``{'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
 
 This should essentially be the mapping of the contents of ``POLICY_FILES_PATH``
 to service types.  When policy.json files are added to the directory
@@ -102,7 +102,7 @@ x tuples can be added to enforce x rules.
 
 .. note::
 
-    If a rule specified is not found in the policy file. The policy check
+    If a rule specified is not found in the policy file, the policy check
     will return False and the action will not be allowed.
 
 The secondary way to add a role based check is to directly use the
@@ -144,5 +144,5 @@ then access is allowed.
 When deriving the :class:`horizon.tables.Action` class for use in a table, if
 a policy check is desired for a particular target, the implementer should
 override the :meth:`horizon.tables.Action.get_policy_target` method. This
-allows a programatic way to specify the target based on the current datum. The
+allows a programmatic way to specify the target based on the current datum. The
 value returned should be the target dictionary.

doc/source/topics/settings.rst

@@ -21,8 +21,8 @@ and a few notes on the Django-related settings.
 
     Prior to the Essex release of Horizon there were settings which controlled
     whether features such as Object Storage/Swift or Networking/Neutron would be
-    enabled in the OpenStack Dashboard. This code has beenlong-since removed and
+    enabled in the OpenStack Dashboard. This code has long since been removed
-    those pre-Essex settings have no impact now.
+    and those pre-Essex settings have no impact now.
 
     In Essex and later, the Service Catalog returned by the Identity Service
     after a user has successfully authenticated determines the dashboards and
@@ -83,7 +83,7 @@ expressed in milliseconds.
 ``help_url``
 ------------
 
-Default: None
+Default: ``None``
 
 If provided, a "Help" link will be displayed in the site header which links
 to the value of this settings (ideally a URL containing help information).
@@ -99,7 +99,7 @@ exception handling should be aware of.
 ``password_validator``
 ----------------------
 
-Default: {'regex': '.*', 'help_text': _("Password is not accepted")}
+Default: ``{'regex': '.*', 'help_text': _("Password is not accepted")}``
 
 A dictionary containing a regular expression which will be used for password
 validation and help text which will be displayed if the password does not
@@ -183,7 +183,7 @@ If you do not have multiple regions you should use the ``OPENSTACK_HOST`` and
 ``OPENSTACK_KEYSTONE_DEFAULT_ROLE``
 -----------------------------------
 
-Default: "Member"
+Default: ``"Member"``
 
 The name of the role which will be assigned to a user when added to a project.
 This name must correspond to a role name in Keystone.
@@ -280,7 +280,7 @@ define the policy rules actions are verified against.
 ``POLICY_FILES``
 ----------------
 
-Default: ``{ 'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
+Default: ``{'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
 
 This should essentially be the mapping of the contents of ``POLICY_FILES_PATH``
 to service types.  When policy.json files are added to ``POLICY_FILES_PATH``,
@@ -289,10 +289,22 @@ they should be included here too.
 ``OPENSTACK_IMAGE_BACKEND``
 ---------------------------
 
-Default: ``{ 'image_formats': [('', ''), ('aki', _('AKI - Amazon Kernel Image')),
+Default::
-('ami', _('AMI - Amazon Machine Image')), ('ari', _('ARI - Amazon Ramdisk Image')),
+
-('iso', _('ISO - Optical Disk Image')), ('qcow2', _('QCOW2 - QEMU Emulator')),
+    {
-('raw', _('Raw')), ('vdi', _('VDI')), ('vhd', _('VHD')), ('vmdk', _('VMDK'))] }``
+        'image_formats': [
+            ('', ''),
+            ('aki', _('AKI - Amazon Kernel Image')),
+            ('ami', _('AMI - Amazon Machine Image')),
+            ('ari', _('ARI - Amazon Ramdisk Image')),
+            ('iso', _('ISO - Optical Disk Image')),
+            ('qcow2', _('QCOW2 - QEMU Emulator')),
+            ('raw', _('Raw')),
+            ('vdi', _('VDI')),
+            ('vhd', _('VHD')),
+            ('vmdk', _('VMDK'))
+        ]
+    }
 
 Used to customize features related to the image service, such as the list of
 supported image formats.

doc/source/topics/testing.rst

@@ -59,7 +59,7 @@ Cons:
   in terms of inputs and outputs.
 * Often requires writing a separate set of tests and/or using a different
   testing framework from your unit tests.
-* Don't offer any insight into the quality or status of the underlying code,
+* Doesn't offer any insight into the quality or status of the underlying code,
   only verifies that it works or it doesn't.
 
 Integration Tests
@@ -170,7 +170,7 @@ is tested... these types of things aren't always easy, but they're extremely
 necessary.
 
 To that end, Horizon includes several custom assertions to make these tasks
-easier. :meth:`~horizon.test.helpers.TestCase.assertNoFormErrors`,
+easier. :meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors`,
 :meth:`~horizon.test.helpers.TestCase.assertMessageCount`, and
 :meth:`~horizon.test.helpers.TestCase.assertNoMessages` all exist for exactly
 these purposes. Moreover, they provide useful output when things go wrong so
@@ -185,10 +185,10 @@ Debugging Unit Tests
 Tips and tricks
 ---------------
 
-#. Use :meth:`~horizon.test.helpers.TestCase.assertNoFormErrors` immediately
+#. Use :meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors`
-   after your ``client.post`` call for tests that handle form views. This will
+   immediately after your ``client.post`` call for tests that handle form views.
-   immediately fail if your form POST failed due to a validation error and
+   This will immediately fail if your form POST failed due to a validation error
-   tell you what the error was.
+   and tell you what the error was.
 
 #. Use :meth:`~horizon.test.helpers.TestCase.assertMessageCount` and
    :meth:`~horizon.test.helpers.TestCase.assertNoMessages` when a piece of code
@@ -270,7 +270,7 @@ Expected Method Never Called
 This one is the opposite of the unexpected method call. This one means you
 told mox to expect a call and it didn't happen. This is almost always the
 result of an error in the conditions of the test. Using the
-:meth:`~horizon.test.helpers.TestCase.assertNoFormErrors` and
+:meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors` and
 :meth:`~horizon.test.helpers.TestCase.assertMessageCount` will make it readily
 apparent what the problem is in the majority of cases. If not, then use ``pdb``
 and start interrupting the code flow to see where things are getting off track.

doc/source/topics/tutorial.rst

@@ -159,7 +159,7 @@ Structure
 A panel is a relatively flat structure with the exception that templates
 for a panel in a dashboard live in the dashboard's ``templates`` directory
 rather than in the panel's ``templates`` directory. Continuing our
-vizulaization/flocking example, let's see what the looks like::
+visualization/flocking example, let's see what the file structure looks like::
 
     # stand-alone panel structure
     flocking/
@@ -281,7 +281,7 @@ make everything translatable, we give each column a ``verbose_name`` that's
 marked for translation.
 
 Lastly, we added a ``Meta`` class which defines some properties about our
-table, notably it's (translatable) verbose name, and a semi-unique "slug"-like
+table, notably its (translatable) verbose name, and a semi-unique "slug"-like
 name to identify it.
 
 .. note::
@@ -311,7 +311,7 @@ First off, let's make a tab for our visualization::
             return None
 
 This is about as simple as you can get. Since our visualization will
-ultiimately use AJAX to load it's data we don't need to pass any context
+ultimately use AJAX to load it's data we don't need to pass any context
 to the template, and all we need to define is the name and which template
 it should use.
 
@@ -458,12 +458,12 @@ A site built on Horizon takes the form of a very typical Django project::
          |--static/
 
 The key bits here are that ``demo_dashboard`` is on our python path, and that
-the `settings.py`` file here will contain our customized Horizon config.
+the ``settings.py`` file here will contain our customized Horizon config.
 
 The settings file
 -----------------
 
-There are several key things you will generally want to customiz in your
+There are several key things you will generally want to customize in your
 site's settings file: specifying custom dashboards and panels, catching your
 client's exception classes, and (possibly) specifying a file for advanced
 overrides.
@@ -521,7 +521,7 @@ routines for the entire site. By specifying an override file you can alter
 any behavior you like in existing code. This tutorial won't go in-depth,
 but let's just say that with great power comes great responsibility.
 
-To specify am override file, you set the ``'customization_module'`` value in
+To specify an override file, you set the ``'customization_module'`` value in
 the ``HORIZON_CONFIG`` dictionary to the dotted python path of your
 override module::