Improve contributor documentation

Fix various errors in the contributor documentation:

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

Change-Id: I4863ca10a532ac74491cfb19f8382e3d5287d2f3
This commit is contained in:
Ana Krivokapic 2013-12-03 19:58:19 +01:00
parent 258e9b4653
commit d3c91de71a
14 changed files with 76 additions and 61 deletions

View File

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

View File

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

View File

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

View File

@ -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
``openstack-dashboard/tools/install_venv.py``.
#. Run the tests for both ``horizon`` and ``openstack-dashboard`` using
their respective environments and verify that evreything is working.
the ``openstack_dashboard`` project using ``./tools/install_venv.py``.
#. Run the tests for both ``horizon`` and ``openstack_dashboard`` using
their respective environments and verify that everything 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

View File

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

View File

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

View File

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

View File

@ -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:

View File

@ -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
can be overriden.
template ``horizon/templates/base.html`` defines multiple blocks that
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

View File

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

View File

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

View File

@ -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
those pre-Essex settings have no impact now.
enabled in the OpenStack Dashboard. This code has long since been removed
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')),
('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'))] }``
Default::
{
'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.

View File

@ -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
after your ``client.post`` call for tests that handle form views. This will
immediately fail if your form POST failed due to a validation error and
tell you what the error was.
#. Use :meth:`~openstack_dashboard.test.helpers.TestCase.assertNoFormErrors`
immediately after your ``client.post`` call for tests that handle form views.
This will immediately fail if your form POST failed due to a validation error
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.

View File

@ -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::