diff --git a/cloudkitty/rating/hash/datamodels/service.py b/cloudkitty/rating/hash/datamodels/service.py
index f31ea6ca..6c0868f8 100644
--- a/cloudkitty/rating/hash/datamodels/service.py
+++ b/cloudkitty/rating/hash/datamodels/service.py
@@ -40,9 +40,7 @@ class Service(wtypes.Base):
 
 
 class ServiceCollection(wtypes.Base):
-    """Type describing a list of services.
-
-    """
+    """Type describing a list of services."""
 
     services = [Service]
     """List of services."""
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
new file mode 100644
index 00000000..e42f2984
--- /dev/null
+++ b/doc/source/admin/index.rst
@@ -0,0 +1,10 @@
+====================
+Administration Guide
+====================
+
+.. toctree::
+   :glob:
+
+   rating/introduction.rst
+   rating/hashmap.rst
+   rating/pyscripts.rst
diff --git a/doc/source/rating/graph/hashmap.dot b/doc/source/admin/rating/graph/hashmap.dot
similarity index 100%
rename from doc/source/rating/graph/hashmap.dot
rename to doc/source/admin/rating/graph/hashmap.dot
diff --git a/doc/source/rating/hashmap.rst b/doc/source/admin/rating/hashmap.rst
similarity index 100%
rename from doc/source/rating/hashmap.rst
rename to doc/source/admin/rating/hashmap.rst
diff --git a/doc/source/rating/introduction.rst b/doc/source/admin/rating/introduction.rst
similarity index 100%
rename from doc/source/rating/introduction.rst
rename to doc/source/admin/rating/introduction.rst
diff --git a/doc/source/rating/pyscripts.rst b/doc/source/admin/rating/pyscripts.rst
similarity index 100%
rename from doc/source/rating/pyscripts.rst
rename to doc/source/admin/rating/pyscripts.rst
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 00000000..d4c2f17e
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,10 @@
+#############
+API Reference
+#############
+
+.. toctree::
+   :glob:
+
+   webapi/root
+   webapi/v1
+   webapi/rating/*
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a2dd4deb..ad4f29cd 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -1,9 +1,11 @@
 # -*- coding: utf-8 -*-
+# Copyright (c) 2010 OpenStack Foundation.
+#
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-# http://www.apache.org/licenses/LICENSE-2.0
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
@@ -12,58 +14,83 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#
+# This file is execfile()'d with the current directory set to its containing
+# dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
 import os
+import subprocess
 import sys
+import warnings
+
+import openstackdocstheme
 
 
-sys.path.insert(0, os.path.abspath('../..'))
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path = [
+    os.path.abspath('../..'),
+    os.path.abspath('../../bin')
+    ] + sys.path
 
-# -- General configuration ----------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+# -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.graphviz',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.mathjax',
-    'wsmeext.sphinxext',
-    'sphinxcontrib.pecanwsme.rest',
-    'sphinxcontrib.httpdomain',
-    'openstackdocstheme'
-]
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.coverage',
+              'sphinx.ext.ifconfig',
+              'sphinx.ext.graphviz',
+              'stevedore.sphinxext',
+              'oslo_config.sphinxext',
+              'sphinx.ext.autodoc',
+              'sphinx.ext.viewcode',
+              'oslo_config.sphinxconfiggen',
+              'sphinx.ext.mathjax',
+              'wsmeext.sphinxext',
+              'sphinxcontrib.pecanwsme.rest',
+              'sphinxcontrib.httpdomain',
+              'openstackdocstheme',
+              ]
 
-wsme_protocols = ['restjson', 'restxml']
+# openstackdocstheme options
+repository_name = 'openstack/cloudkitty'
+bug_project = 'cloudkitty'
+bug_tag = ''
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+# templates_path = []
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+#source_encoding = 'utf-8'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'cloudkitty'
-copyright = u'2014, Objectif Libre'
+project = u'Cloudkitty'
+copyright = u'2014-present, OpenStack Foundation.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+from cloudkitty.version import version_info as cloudkitty_version
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = cloudkitty_version.version_string_with_vcs()
+# The short X.Y version.
+version = cloudkitty_version.canonical_version_string()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -75,12 +102,15 @@ release = '0.1'
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+#exclude_trees = ['api']
 exclude_patterns = []
 
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
+# The reST default role (for this markup: `text`) to use for all documents.
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -92,7 +122,7 @@ add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+show_authors = True
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -100,14 +130,22 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['cloudkitty.']
 
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+# -- Options for man page output --------------------------------------------
 
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
 
-# -- Options for HTML output --------------------------------------------------
+man_pages = [
+    ('index', 'cloudkitty', u'cloudkitty Documentation',
+     [u'Objectif Libre'], 1)
+]
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
 html_theme = 'openstackdocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -116,7 +154,8 @@ html_theme = 'openstackdocs'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = ["."]
+#html_theme_path = ['_theme']
+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".
@@ -137,17 +176,19 @@ html_theme = 'openstackdocs'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+   "-n1"]
+try:
+    html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8')
+except Exception:
+    warnings.warn('Cannot get last updated time from git repository. '
+                  'Not setting "html_last_updated_fmt".')
+
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -161,10 +202,10 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_use_modindex = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
@@ -172,43 +213,32 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 # If true, links to the reST sources are added to the pages.
 #html_show_sourcelink = True
 
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'cloudkittydoc'
 
 
-# -- Options for LaTeX output -------------------------------------------------
+# -- Options for LaTeX output ------------------------------------------------
 
-latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-}
+#latex_font_size = '10pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+# (source start file, target name, title, author,
+# documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'cloudkitty.tex', u'cloudkitty Documentation',
-   u'Objectif Libre', 'manual'),
+    ('index', 'Cloudkitty.tex', u'Cloudkitty Documentation',
+     u'Cloudkitty Team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -219,56 +249,11 @@ latex_documents = [
 # not chapters.
 #latex_use_parts = False
 
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output -------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    ('index', 'cloudkitty', u'cloudkitty Documentation',
-     [u'Objectif Libre'], 1)
-]
-
-# If true, show URL addresses after external links.
-#man_show_urls = False
-
-
-# -- Options for Texinfo output -----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-  ('index', 'cloudkitty', u'cloudkitty Documentation',
-   u'Objectif Libre', 'cloudkitty', 'One line description of project.',
-   'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
-
-# -- Options for openstackdocstheme -------------------------------------------
-repository_name = 'openstack/cloudkitty'
-bug_project = 'cloudkitty'
-bug_tag = ''
+#latex_use_modindex = True
diff --git a/doc/source/installation.rst b/doc/source/configuration/index.rst
similarity index 66%
rename from doc/source/installation.rst
rename to doc/source/configuration/index.rst
index c8a902e3..3cbab9a7 100644
--- a/doc/source/installation.rst
+++ b/doc/source/configuration/index.rst
@@ -1,117 +1,8 @@
-#########################################
-Cloudkitty installation and configuration
-#########################################
+###################
+Configuration Guide
+###################
 
-Many method can be followed to install cloudkitty.
-
-Install from source
-===================
-
-Install the services
---------------------
-
-Retrieve and install cloudkitty::
-
-    git clone https://git.openstack.org/openstack/cloudkitty.git
-    cd cloudkitty
-    python setup.py install
-
-This procedure installs the ``cloudkitty`` python library and the
-following executables:
-
-* ``cloudkitty-api``: API service
-* ``cloudkitty-processor``: Processing service (collecting and rating)
-* ``cloudkitty-dbsync``: Tool to create and upgrade the database schema
-* ``cloudkitty-storage-init``: Tool to initiate the storage backend
-* ``cloudkitty-writer``: Reporting tool
-
-Install sample configuration files::
-
-    mkdir /etc/cloudkitty
-    tox -e genconfig
-    cp etc/cloudkitty/cloudkitty.conf.sample /etc/cloudkitty/cloudkitty.conf
-    cp etc/cloudkitty/policy.json /etc/cloudkitty
-    cp etc/cloudkitty/api_paste.ini /etc/cloudkitty
-
-Create the log directory::
-
-    mkdir /var/log/cloudkitty/
-
-Install the client
-------------------
-
-Retrieve and install cloudkitty client::
-
-    git clone https://git.openstack.org/openstack/python-cloudkittyclient.git
-    cd python-cloudkittyclient
-    python setup.py install
-
-Install the dashboard module
-----------------------------
-
-#. Retrieve and install cloudkitty's dashboard::
-
-    git clone https://git.openstack.org/openstack/cloudkitty-dashboard.git
-    cd cloudkitty-dashboard
-    python setup.py install
-
-#. Find where the python packages are installed::
-
-    PY_PACKAGES_PATH=`pip --version | cut -d' ' -f4`
-
-#. Add the enabled file to the horizon settings or installation.
-   Depending on your setup, you might need to add it to ``/usr/share`` or
-   directly in the horizon python package::
-
-    # If horizon is installed by packages:
-    ln -sf $PY_PACKAGES_PATH/cloudkittydashboard/enabled/_[0-9]*.py \
-    /usr/share/openstack-dashboard/openstack_dashboard/enabled/
-
-    # Directly from sources:
-    ln -sf $PY_PACKAGES_PATH/cloudkittydashboard/enabled/_[0-9]*.py \
-    $PY_PACKAGES_PATH/openstack_dashboard/enabled/
-
-#. Restart the web server hosting Horizon.
-
-
-Install from packages
-=====================
-
-For RHEL/CentOS 7
------------------
-
-Packages for RHEL/CentOS 7 are available starting from the Mitaka release.
-
-#. Install the RDO repositories for your release::
-
-    yum install centos-release-openstack-RELEASE # RELEASE can be mitaka, newton or ocata
-
-#. Install the packages::
-
-    yum install openstack-cloudkitty-api openstack-cloudkitty-processor openstack-cloudkitty-ui
-
-
-For Ubuntu 16.04
-----------------
-
-Packages for Ubuntu 16.04 are available starting from the Newton release.
-
-#. Enable the OpenStack repository for the Newton or Ocata release::
-
-    apt install software-properties-common
-    add-apt-repository ppa:objectif-libre/cloudkitty # Newton
-    add-apt-repository ppa:objectif-libre/cloudkitty-ocata # Ocata
-
-#. Upgrade the packages on your host::
-
-    apt update && apt dist-upgrade
-
-#. Install the packages::
-
-    apt-get install cloudkitty-api cloudkitty-processor cloudkitty-dashboard
-
-
-Configure cloudkitty
+Configure Cloudkitty
 ====================
 
 Edit :file:`/etc/cloudkitty/cloudkitty.conf` to configure cloudkitty.
@@ -261,7 +152,7 @@ documentation), and Gnocchi.
     auth_section = ks_auth
 
 Setup the database and storage backend
-======================================
+--------------------------------------
 
 MySQL/MariaDB is the recommended database engine. To setup the database, use
 the ``mysql`` client::
@@ -284,8 +175,8 @@ Init the storage backend::
     cloudkitty-storage-init
 
 
-Setup Keystone
-==============
+Integration with Keystone
+-------------------------
 
 cloudkitty uses Keystone for authentication, and provides a ``rating`` service.
 
@@ -345,7 +236,7 @@ Choose and start the API server
    used to run the API server. For smaller or proof-of-concept
    installations this is a reasonable choice. For larger installations it
    is strongly recommended to install the API server in a WSGI host
-   such as mod_wsgi (see :doc:`mod_wsgi`). Doing so will provide better
+   such as mod_wsgi (see :ref:`mod_wsgi`). Doing so will provide better
    performance and more options for making adjustments specific to the
    installation environment.
 
@@ -353,4 +244,3 @@ Choose and start the API server
    as::
 
     $ cloudkitty-api -p 8889
-
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 51e9332b..b7729a25 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,69 +3,19 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-=================================================
-Welcome to CloudKitty's developer documentation!
-=================================================
-
-Introduction
-============
+======================================
+Welcome to CloudKitty's documentation!
+======================================
 
 CloudKitty is a Rating As A Service project aimed at translating metrics
 to prices.
 
-Installation
-============
-
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
+   install/index
+   configuration/index
+   admin/index
    devstack
-   installation
-   mod_wsgi
-
-
-Architecture
-============
-
-.. toctree::
-   :maxdepth: 1
-
    arch
-
-
-API References
-==============
-
-.. toctree::
-   :maxdepth: 1
-
-   webapi/root
-   webapi/v1
-
-
-Modules API
-===========
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   webapi/rating/*
-
-Rating Module Documentation
-===========================
-
-.. toctree::
-   :maxdepth: 1
-
-   rating/introduction.rst
-   rating/hashmap.rst
-   rating/pyscripts.rst
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   api
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
new file mode 100644
index 00000000..c6d3f134
--- /dev/null
+++ b/doc/source/install/index.rst
@@ -0,0 +1,11 @@
+==================
+Installation Guide
+==================
+
+.. toctree::
+   :glob:
+
+   install-source
+   install-ubuntu
+   install-rdo
+   mod_wsgi
diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst
new file mode 100644
index 00000000..8e129d4d
--- /dev/null
+++ b/doc/source/install/install-rdo.rst
@@ -0,0 +1,12 @@
+Install from package (RDO For RHEL/CentOS 7)
+============================================
+
+Packages for RHEL/CentOS 7 are available starting from the Mitaka release.
+
+#. Install the RDO repositories for your release::
+
+    yum install centos-release-openstack-RELEASE # RELEASE can be mitaka, newton or ocata
+
+#. Install the packages::
+
+    yum install openstack-cloudkitty-api openstack-cloudkitty-processor openstack-cloudkitty-ui
diff --git a/doc/source/install/install-source.rst b/doc/source/install/install-source.rst
new file mode 100644
index 00000000..fd5d9fe0
--- /dev/null
+++ b/doc/source/install/install-source.rst
@@ -0,0 +1,68 @@
+Install from source
+===================
+
+Install the services
+--------------------
+
+Retrieve and install cloudkitty::
+
+    git clone https://git.openstack.org/openstack/cloudkitty.git
+    cd cloudkitty
+    python setup.py install
+
+This procedure installs the ``cloudkitty`` python library and the
+following executables:
+
+* ``cloudkitty-api``: API service
+* ``cloudkitty-processor``: Processing service (collecting and rating)
+* ``cloudkitty-dbsync``: Tool to create and upgrade the database schema
+* ``cloudkitty-storage-init``: Tool to initiate the storage backend
+* ``cloudkitty-writer``: Reporting tool
+
+Install sample configuration files::
+
+    mkdir /etc/cloudkitty
+    tox -e genconfig
+    cp etc/cloudkitty/cloudkitty.conf.sample /etc/cloudkitty/cloudkitty.conf
+    cp etc/cloudkitty/policy.json /etc/cloudkitty
+    cp etc/cloudkitty/api_paste.ini /etc/cloudkitty
+
+Create the log directory::
+
+    mkdir /var/log/cloudkitty/
+
+Install the client
+------------------
+
+Retrieve and install cloudkitty client::
+
+    git clone https://git.openstack.org/openstack/python-cloudkittyclient.git
+    cd python-cloudkittyclient
+    python setup.py install
+
+Install the dashboard module
+----------------------------
+
+#. Retrieve and install cloudkitty's dashboard::
+
+    git clone https://git.openstack.org/openstack/cloudkitty-dashboard.git
+    cd cloudkitty-dashboard
+    python setup.py install
+
+#. Find where the python packages are installed::
+
+    PY_PACKAGES_PATH=`pip --version | cut -d' ' -f4`
+
+#. Add the enabled file to the horizon settings or installation.
+   Depending on your setup, you might need to add it to ``/usr/share`` or
+   directly in the horizon python package::
+
+    # If horizon is installed by packages:
+    ln -sf $PY_PACKAGES_PATH/cloudkittydashboard/enabled/_[0-9]*.py \
+    /usr/share/openstack-dashboard/openstack_dashboard/enabled/
+
+    # Directly from sources:
+    ln -sf $PY_PACKAGES_PATH/cloudkittydashboard/enabled/_[0-9]*.py \
+    $PY_PACKAGES_PATH/openstack_dashboard/enabled/
+
+#. Restart the web server hosting Horizon.
diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst
new file mode 100644
index 00000000..fb4ef3c0
--- /dev/null
+++ b/doc/source/install/install-ubuntu.rst
@@ -0,0 +1,18 @@
+Install from packages for Ubuntu (16.04)
+========================================
+
+Packages for Ubuntu 16.04 are available starting from the Newton release.
+
+#. Enable the OpenStack repository for the Newton or Ocata release::
+
+    apt install software-properties-common
+    add-apt-repository ppa:objectif-libre/cloudkitty # Newton
+    add-apt-repository ppa:objectif-libre/cloudkitty-ocata # Ocata
+
+#. Upgrade the packages on your host::
+
+    apt update && apt dist-upgrade
+
+#. Install the packages::
+
+    apt-get install cloudkitty-api cloudkitty-processor cloudkitty-dashboard
diff --git a/doc/source/mod_wsgi.rst b/doc/source/install/mod_wsgi.rst
similarity index 81%
rename from doc/source/mod_wsgi.rst
rename to doc/source/install/mod_wsgi.rst
index e9de644e..0f718c63 100644
--- a/doc/source/mod_wsgi.rst
+++ b/doc/source/install/mod_wsgi.rst
@@ -13,9 +13,11 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-===================================
- Installing the API behind mod_wsgi
-===================================
+.. _mod_wsgi:
+
+==================================
+Installing the API behind mod_wsgi
+==================================
 
 Cloudkitty comes with a few example files for configuring the API
 service to run behind Apache with ``mod_wsgi``.
@@ -24,7 +26,7 @@ app.wsgi
 ========
 
 The file ``cloudkitty/api/app.wsgi`` sets up the V1 API WSGI
-application. The file needs to be copied to /var/www/cloudkitty/,
+application. The file needs to be copied to ``/var/www/cloudkitty/``,
 and should not need to be modified.
 
 etc/apache2/cloudkitty
@@ -33,7 +35,7 @@ etc/apache2/cloudkitty
 The ``etc/apache2/cloudkitty`` file contains example settings that
 work with a copy of cloudkitty installed via devstack.
 
-.. literalinclude:: ../../etc/apache2/cloudkitty
+.. literalinclude:: ../../../etc/apache2/cloudkitty
 
 1. On deb-based systems copy or symlink the file to
    ``/etc/apache2/sites-available``. For rpm-based systems the file will go in
@@ -45,9 +47,9 @@ work with a copy of cloudkitty installed via devstack.
 
 3. Enable the cloudkitty site. On deb-based systems::
 
-      $ a2ensite cloudkitty
-      $ service apache2 reload
+      # a2ensite cloudkitty
+      # service apache2 reload
 
    On rpm-based systems::
 
-      $ service httpd reload
+      # service httpd reload