diff --git a/doc/source/conf.py b/doc/source/conf.py index ad87236730..be26b37007 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -26,6 +26,7 @@ from __future__ import print_function import django import logging +import openstackdocstheme import os import subprocess import sys @@ -68,7 +69,6 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', - 'oslosphinx', ] # Add any paths that contain templates here, relative to this directory. @@ -140,7 +140,7 @@ nitpicky = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme_path = ['.'] -# html_theme = '_theme' +html_theme = 'openstackdocs' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -150,7 +150,7 @@ html_theme_options = { } # Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] +html_theme_path = [openstackdocstheme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -225,6 +225,20 @@ except Exception: # Output file base name for HTML help builder. htmlhelp_basename = 'Horizondoc' +# We ask git for the SHA checksum +# The git SHA checksum is used by "log-a-bug" +gitsha = subprocess.Popen( + git_cmd, stdout=subprocess.PIPE).communicate()[0].strip('\n') +giturl = u'https://git.openstack.org/cgit/openstack/horizon/tree/doc/source' +# html_context allows us to pass arbitrary values into the html template +html_context = { + "gitsha": gitsha, + "giturl": giturl, + "bug_project": "horizon", + # tag that reported bugs will be tagged with + "bug_tag": "documentation", +} + # -- Options for LaTeX output ------------------------------------------------- diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 0a5f765b18..696d21fdd6 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -4,47 +4,102 @@ Quickstart .. Note :: - This section has been tested for Horizon on Ubuntu (12.04-64) and RPM-based (RHEL 7.x) distributions. Feel free to add notes and any changes according to your experiences or operating system. + This section has been tested for Horizon on Ubuntu (16.04-64) and RPM-based + (RHEL 7.x) distributions. Feel free to add notes and any changes according + to your experiences or operating system. Linux Systems ============= Install the prerequisite packages. -On Ubuntu:: +On Ubuntu - > sudo apt-get install git python-dev python-virtualenv libssl-dev libffi-dev +.. code-block:: console -On RPM-based distributions (e.g., Fedora/RHEL/CentOS/Scientific Linux):: + # sudo apt-get install git python-pip - > sudo yum install gcc git-core python-devel python-virtualenv openssl-devel libffi-devel which +On RPM-based distributions (e.g., Fedora/RHEL/CentOS/Scientific Linux) + +.. code-block:: console + + # sudo yum install gcc git-core python-devel python-virtualenv openssl-devel libffi-devel which + +.. note:: + + Some tests rely on the Chrome web browser being installed. While the above + requirements will allow you to run and manually test Horizon, you will + need to install Chrome to run the full test suite. Setup ===== To begin setting up a Horizon development environment simply clone the Horizon -git repository from https://git.openstack.org/cgit/openstack/horizon.:: +git repository from https://git.openstack.org/cgit/openstack/horizon - > git clone https://git.openstack.org/openstack/horizon +.. code-block:: console -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:: + # git clone https://git.openstack.org/openstack/horizon - > cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py +Next you will need to configure Horizon by adding a ``local_settings.py`` file. +A good starting point is to use the example config with the following command, +from within the ``horizon`` directory. + +.. code-block:: console + + # cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py + +Horizon connects to the rest of OpenStack via a Keystone service catalog. By +default Horizon looks for an endpoint at ``http://localhost:5000/v2.0``; this +can be customised by modifying the ``OPENSTACK_HOST`` and +``OPENSTACK_KEYSTONE_URL`` values in +``openstack_dashboard/local/local_settings.py`` .. note:: - To add new settings or customize existing settings, modify the ``local_settings.py`` file. + The DevStack project (http://devstack.org/) can be used to install + an OpenStack development environment from scratch. For a local.conf that + enables most services that Horizon supports managing, see + :doc:`local.conf ` -Horizon assumes a single end-point for OpenStack services which defaults to -the local host (127.0.0.1), as is the default in DevStack. If this is not the -case change the ``OPENSTACK_HOST`` setting in the -``openstack_dashboard/local/local_settings.py`` file, to the actual IP address -of the OpenStack end-point Horizon should use. +Horizon uses ``tox`` to manage virtual environments for testing and other +development tasks. You can install it with + +.. code-block:: console + + # pip install tox + +The ``tox`` environments provide wrappers around ``manage.py``. For more +information on ``manage.py``, which is a Django command, see +https://docs.djangoproject.com/en/dev/ref/django-admin/ + +To start the Horizon development server use the command below + +.. code-block:: console + + # tox -e runserver + +.. note:: + + The default port for runserver is 8000 which is already consumed by + heat-api-cfn in DevStack. If running in DevStack + ``tox -e runserver -- localhost:9000`` will start the test server at + ``http://localhost:9000`` + +Once the Horizon server is running, point a web browser to ``http://localhost`` +or to the IP and port the server is listening for. Enter your Keystone +credentials, log in and you'll be presented with the Horizon dashboard. +Congratulations! + +Managing Settings +================= You can save changes you made to -``openstack_dashboard/local/local_settings.py`` with the following command:: +``openstack_dashboard/local/local_settings.py`` with the following command: - > python manage.py migrate_settings --gendiff +.. code-block:: console + + # python manage.py migrate_settings --gendiff .. note:: @@ -54,14 +109,18 @@ You can save changes you made to If you upgrade Horizon, you might need to update your ``openstack_dashboard/local/local_settings.py`` file with new parameters from ``openstack_dashboard/local/local_settings.py.example`` to do so, first update -Horizon:: +Horizon - > git remote update && git pull --ff-only origin master +.. code-block:: console -Then update your ``openstack_dashboard/local/local_settings.py`` file:: + # git remote update && git pull --ff-only origin master - > mv openstack_dashboard/local/local_settings.py openstack_dashboard/local/local_settings.py.old - > python manage.py migrate_settings +Then update your ``openstack_dashboard/local/local_settings.py`` file + +.. code-block:: console + + # mv openstack_dashboard/local/local_settings.py openstack_dashboard/local/local_settings.py.old + # python manage.py migrate_settings .. note:: @@ -77,55 +136,12 @@ Then update your ``openstack_dashboard/local/local_settings.py`` file:: ``openstack_dashboard/local/local_settings.py.example`` file. When all settings have been migrated, it is safe to regenerate a clean diff in -order to prevent Conflicts for future migrations:: +order to prevent Conflicts for future migrations - > mv openstack_dashboard/local/local_settings.diff openstack_dashboard/local/local_settings.diff.old - > python manage.py migrate_settings --gendiff - -To start the Horizon development server use ``tox``:: - - > tox -e runserver - -.. note:: - - The default port for runserver is 8000 which is already consumed by - heat-api-cfn in DevStack. If running in DevStack - `tox -e runserver -- localhost:9000` will start the test server at - `http://localhost:9000`. - - -.. note:: - - The ``tox`` environments provide wrappers around ``manage.py``. - For more information on manage.py which is a django, see - `https://docs.djangoproject.com/en/dev/ref/django-admin/` - - -Once the Horizon server is running, point a web browser to http://localhost:9000 -or to the IP and port the server is listening for. - -.. note:: - - The ``DevStack`` project (http://devstack.org/) can be used to install - an OpenStack development environment from scratch. For a local.conf that - enables most services that Horizon supports managing see - :doc:`local.conf ` - -.. note:: - - The minimum required set of OpenStack services running includes the - following: - - * Nova (compute, api, scheduler, and network) - * Glance - * Keystone - * Neutron (unless nova-network is used) - - Horizon provides optional support for other services. - See :ref:`system-requirements-label` for the supported services. - If Keystone endpoint for a service is configured, Horizon detects it - and enables its support automatically. +.. code-block:: console + # mv openstack_dashboard/local/local_settings.diff openstack_dashboard/local/local_settings.diff.old + # python manage.py migrate_settings --gendiff Editing Horizon's Source ======================== @@ -133,23 +149,20 @@ Editing Horizon's Source Although DevStack installs and configures an instance of Horizon when running stack.sh, the preferred development setup follows the instructions above on the server/VM running DevStack. There are several advantages to maintaining a -separate copy of the Horizon repo, rather than editing the devstack installed +separate copy of the Horizon repo, rather than editing the DevStack installed copy. - * Source code changes aren't as easily lost when running unstack.sh/stack.sh - * The development server picks up source code changes (other than JavaScript - and CSS due to compression and compilation) while still running. - * Log messages and print statements go directly to the console. - * Debugging with pdb becomes much simpler to interact with. +- Source code changes aren't as easily lost when running ``unstack.sh`` / + ``stack.sh`` +- The development server picks up source code changes while still running. +- Log messages and print statements go directly to the console. +- Debugging with ``pdb`` becomes much simpler to interact with. -.. Note:: - JavaScript and CSS changes require a development server restart. Also, - forcing a refresh of the page (e.g. using Shift-F5) in the browser is - required to pull down non-cached versions of the CSS and JavaScript. The - default setting in Horizon is to do compilation and compression of these - files at server startup. If you have configured your local copy to do - offline compression, more steps are required. +.. note:: + To ensure that JS and CSS changes are picked up without a server restart, you + can disable compression with ``COMPRESS_ENABLED = False`` in your local + settings file. Horizon's Structure =================== @@ -171,9 +184,8 @@ virtualenv and installs all the necessary packages. If dependencies are added to either ``horizon`` or ``openstack_dashboard``, they should be added to ``requirements.txt``. - -Project -======= +Project Structure +================= Dashboard configuration ----------------------- @@ -190,7 +202,9 @@ advantage of the pluggable settings feature. URLs ---- -Then you add a single line to your project's ``urls.py``:: +Then you add a single line to your project's ``urls.py`` + +.. code-block:: python url(r'', include(horizon.urls)), @@ -201,33 +215,39 @@ Templates --------- Pre-built template tags generate navigation. In your ``nav.html`` -template you might have the following:: +template you might have the following + +.. code-block:: htmldjango {% load horizon %}
- {% horizon_main_nav %} + {% horizon_main_nav %}
-And in your ``sidebar.html`` you might have:: +And in your ``sidebar.html`` you might have + +.. code-block:: htmldjango {% load horizon %}
- {% horizon_dashboard_nav %} + {% horizon_dashboard_nav %}
These template tags are aware of the current "active" dashboard and panel via template context variables and will render accordingly. -Application -=========== +Application Design +================== Structure --------- An application would have the following structure (we'll use project as -an example):: +an example) + +.. code-block:: console project/ |---__init__.py @@ -249,7 +269,9 @@ Dashboard Classes ----------------- Inside of ``dashboard.py`` you would have a class definition and the registration -process:: +process + +.. code-block:: python import horizon @@ -277,7 +299,9 @@ Panel Classes ------------- To connect a :class:`~horizon.Panel` with a :class:`~horizon.Dashboard` class -you register it in a ``panel.py`` file like so:: +you register it in a ``panel.py`` file + +.. code-block:: python import horizon @@ -290,7 +314,6 @@ you register it in a ``panel.py`` file like so:: permissions = ('openstack.roles.admin', 'my.openstack.permission',) policy_rules = (('endpoint', 'endpoint:rule'),) - # You could also register your panel with another application's dashboard dashboard.Project.register(Images) diff --git a/openstack_dashboard/local/local_settings.py.example b/openstack_dashboard/local/local_settings.py.example index 37025a16fa..3e3d448084 100644 --- a/openstack_dashboard/local/local_settings.py.example +++ b/openstack_dashboard/local/local_settings.py.example @@ -10,6 +10,16 @@ from openstack_dashboard.settings import HORIZON_CONFIG DEBUG = True +# This setting controls whether or not compression is enabled. Disabling +# compression makes Horizon considerably slower, but makes it much easier +# to debug JS and CSS changes +#COMPRESS_ENABLED = not DEBUG + +# This setting controls whether compression happens on the fly, or offline +# with `python manage.py compress` +# See https://django-compressor.readthedocs.io/en/latest/usage/#offline-compression +# for more information +#COMPRESS_OFFLINE = not DEBUG # WEBROOT is the location relative to Webserver root # should end with a slash. diff --git a/test-requirements.txt b/test-requirements.txt index 96e796b129..86e227ca2b 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -19,6 +19,7 @@ nose-exclude # LGPL nosehtmloutput>=0.0.3 # Apache-2.0 nosexcover # BSD openstack.nose-plugin>=0.7 # Apache-2.0 +openstackdocstheme>=1.5.0 # Apache-2.0 oslosphinx>=4.7.0 # Apache-2.0 reno!=2.3.1,>=1.8.0 # Apache-2.0 requests!=2.12.2,!=2.13.0,>=2.10.0 # Apache-2.0