Update the quickstart guide
This patch is the first in a series improving Horizons documentation. It aims to make the initial quick start section clearer, updates the information to remove some redundant information, and updates the appearance to match the rest of the openstack docs. Change-Id: I942e62b6c2c272dc2b5c91bca42c77677bb4e09d Implements: blueprint pike-docs-overhaul
This commit is contained in:
Rob Cresswell
parent
665a2cd874
commit
6eb8394213
@ -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
|
||||
# "<project> v<release> 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 -------------------------------------------------
|
||||
|
||||
|
||||
@ -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 <ref/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 <ref/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,7 +215,9 @@ 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 %}
|
||||
|
||||
@ -209,7 +225,9 @@ template you might have the following::
|
||||
{% horizon_main_nav %}
|
||||
</div>
|
||||
|
||||
And in your ``sidebar.html`` you might have::
|
||||
And in your ``sidebar.html`` you might have
|
||||
|
||||
.. code-block:: htmldjango
|
||||
|
||||
{% load horizon %}
|
||||
|
||||
@ -220,14 +238,16 @@ And in your ``sidebar.html`` you might have::
|
||||
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)
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user