From d3c91de71a17d4b637022424f6b770e75ae204bf Mon Sep 17 00:00:00 2001 From: Ana Krivokapic Date: Tue, 3 Dec 2013 19:58:19 +0100 Subject: [PATCH] Improve contributor documentation Fix various errors in the contributor documentation: - Factual mistakes (wrong file locations, etc) - Formatting errors - Typos Change-Id: I4863ca10a532ac74491cfb19f8382e3d5287d2f3 --- README.rst | 2 +- doc/source/contributing.rst | 10 +++++++--- doc/source/quickstart.rst | 4 ++-- doc/source/ref/run_tests.rst | 25 ++++++++++++------------ doc/source/releases/2012_1.rst | 10 +++++----- doc/source/releases/2013_1.rst | 6 +++--- doc/source/releases/2013_2.rst | 2 +- doc/source/testing.rst | 2 +- doc/source/topics/customizing.rst | 8 ++++---- doc/source/topics/deployment.rst | 4 ++-- doc/source/topics/policy.rst | 6 +++--- doc/source/topics/settings.rst | 32 +++++++++++++++++++++---------- doc/source/topics/testing.rst | 14 +++++++------- doc/source/topics/tutorial.rst | 12 ++++++------ 14 files changed, 76 insertions(+), 61 deletions(-) diff --git a/README.rst b/README.rst index 75f1dc78c8..68b7ea7580 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index fada39dab3..646d8cfe92 100644 --- a/doc/source/contributing.rst +++ b/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. diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 84d02f4a82..a9b00e0875 100644 --- a/doc/source/quickstart.rst +++ b/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 diff --git a/doc/source/ref/run_tests.rst b/doc/source/ref/run_tests.rst index ca7c7ce18d..47ca6aca92 100644 --- a/doc/source/ref/run_tests.rst +++ b/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 - ``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 @@ -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 --dashboard= @@ -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 diff --git a/doc/source/releases/2012_1.rst b/doc/source/releases/2012_1.rst index e024bf4150..a4037660d1 100644 --- a/doc/source/releases/2012_1.rst +++ b/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. diff --git a/doc/source/releases/2013_1.rst b/doc/source/releases/2013_1.rst index 330a6ae262..82d4f32145 100644 --- a/doc/source/releases/2013_1.rst +++ b/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 diff --git a/doc/source/releases/2013_2.rst b/doc/source/releases/2013_2.rst index 7a39cb9b0e..4e29fdef47 100644 --- a/doc/source/releases/2013_2.rst +++ b/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. diff --git a/doc/source/testing.rst b/doc/source/testing.rst index d9362327e1..7d9a194bc5 100644 --- a/doc/source/testing.rst +++ b/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: diff --git a/doc/source/topics/customizing.rst b/doc/source/topics/customizing.rst index 88b51023f1..848a4d5305 100644 --- a/doc/source/topics/customizing.rst +++ b/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 -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 diff --git a/doc/source/topics/deployment.rst b/doc/source/topics/deployment.rst index f40913d6b9..2cedb2361d 100644 --- a/doc/source/topics/deployment.rst +++ b/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 diff --git a/doc/source/topics/policy.rst b/doc/source/topics/policy.rst index b8253c6b5d..ed549be2d9 100644 --- a/doc/source/topics/policy.rst +++ b/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. diff --git a/doc/source/topics/settings.rst b/doc/source/topics/settings.rst index 5f2558c644..7a1a956867 100644 --- a/doc/source/topics/settings.rst +++ b/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 - 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. diff --git a/doc/source/topics/testing.rst b/doc/source/topics/testing.rst index 06f32258d9..ba1fbd9ede 100644 --- a/doc/source/topics/testing.rst +++ b/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 - 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. diff --git a/doc/source/topics/tutorial.rst b/doc/source/topics/tutorial.rst index a0b561d600..6e3110b412 100644 --- a/doc/source/topics/tutorial.rst +++ b/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::