Horizon Logo Documentation is out of date

Due to recent changes to faciliate logo and favicon overrides,
the documentation was out of date.

Also, it was noted that the theme path needed to get updated as
well because it was recently moved up a directory.

It was noted, while writing the documentation, that styles had
been placed in the 'default' theme that should be global.

Change-Id: I025514b8ff31863858a7941c2380dd8c6397772a
Closes-bug: #1485272

doc/source/topics/customizing.rst

@@ -12,36 +12,76 @@ and a ``_styles.scss`` file with additional styles to load after dashboard
 styles have loaded.
 
 To use a custom theme, set ``CUSTOM_THEME_PATH`` in ``local_settings.py`` to
-the directory location for the theme (e.g., ``"static/themes/blue"``). The
+the directory location for the theme (e.g., ``"themes/blue"``). The
 path can either be relative to the ``openstack_dashboard`` directory or an
 absolute path to an accessible location on the file system. The default
-``CUSTOM_THEME_PATH`` is ``static/themes/default``.
+``CUSTOM_THEME_PATH`` is ``themes/default``.
 
 Both the Dashboard custom variables and Bootstrap variables can be overridden.
 For a full list of the Dashboard SCSS variables that can be changed, see the
 variables file at ``openstack_dashboard/static/dashboard/scss/_variables.scss``.
 
-Changing the Logo
+Organizing Your Theme Directory
+-------------------------------
+
+A custom theme directory can be organized differently, depending on the
+level of customization that is desired, as it can include static files
+as well as Django templates.  It can include special subdirectories that will
+be used differently: ``static``, ``templates`` and ``img``.
+
+The Static Folder
 -----------------
 
-There are currently two places where the OpenStack logo is pulled in
-through the stylesheets. The first is shown at the login screen and the other
-on top of the menu bar. To override the logo place your logo in your themes
-directory and set the image to use in ``_styles.scss``. For example::
+If the theme folder contains a sub-folder called ``static``, then that sub
+folder will be used as the **static root of the theme**.  I.e., Horizon will
+look in that sub-folder for the _variables.scss and _styles.scss files.
+The contents of this folder will also be served up at ``/static/custom``.
 
-    #splash .login {
-      background-image: url(/static/themes/THEME/logo-splash.png);
-    }
+The Templates Folder
+--------------------
 
-    .topbar {
-      h1.brand a {
-        background-image: url(/static/themes/THEME/logo.png);
-      }
-    }
+If the theme folder contains a sub-folder ``templates``, then the path
+to that sub-folder will be prepended to the ``TEMPLATE_DIRS`` tuple to
+allow for theme specific template customizations.
 
-``THEME`` should be replaced by the name of your theme directory.
-The dimensions should be ``width: 216px, height: 35px`` for a drop in
-replacement.
+Using the Templates Folder
+--------------------------
+
+Any Django template that is used in Horizon can be overridden through a theme.
+This allows highly customized user experiences to exist within the scope of
+different themes.  Any template that is overridden must adhere to the same
+directory structure that the extending template expects.
+
+For example, if you wish to customize the sidebar, Horizon expects the template
+to live at ``horizon/_sidebar.html``.  You would need to duplicate that
+directory structure under your templates directory, such that your override
+would live at ``{CUSTOM_THEME_PATH}/templates/horizon/_sidebar.html``.
+
+The Img Folder
+--------------
+
+If the static root of the theme folder contains an ``img`` directory,
+then all images contained within ``dashboard/img`` can be overridden by
+providing a file with the same name.
+
+For a complete list of the images that can be overridden this way, see:
+``openstack_dashboard/static/dashboard/img``
+
+Customizing the Logo
+--------------------
+
+If you wish to customize the logo that is used on the splash screen or in the
+top navigation bar, then you simply need to create an ``img`` directory under
+your theme's static root directory and place your custom ``logo.png`` or
+``logo-splash.png`` within it.
+
+If you wish to override the ``logo.png`` using the previous method, and if the
+image used is larger than the height of the top navbar, then the image will be
+constrained to fit within the height of nav.  You can customize the height of
+the top navigation by customizing the SCSS variable: ``$navbar-height``.
+If the image's height is smaller than the navbar height, then the image
+will retain its original resolution and size, and simply be centered
+vertically in the available space.
 
 Prior to the Kilo release the images files inside of Horizon needed to be
 replaced by your images files or the Horizon stylesheets needed to be altered

doc/source/topics/settings.rst

@@ -393,6 +393,7 @@ This example sorts flavors by vcpus in descending order::
          'reverse': True,
     }
 
+
 ``CUSTOM_THEME_PATH``
 ---------------------
 
@@ -400,21 +401,21 @@ This example sorts flavors by vcpus in descending order::
 
 Default: ``"themes/default"``
 
-This setting allows Horizon to use a custom theme. The theme folder
-should contain one _variables.scss file and one _styles.scss file.
-_variables.scss contains or must import all the bootstrap and horizon
-specific variables which are used to style the GUI. Whereas _styles.scss
-contains extra styling. For example themes, see:
-/horizon/openstack_dashboard/themes/
+This setting tells Horizon to use a directory as a custom theme.
 
-If the static theme folder also contains a sub-folder 'templates', then
-the path to that sub-folder will be prepended to TEMPLATE_DIRS tuple
-to allow for theme specific template customizations.
+By default, this directory will serve as the static root of the theme
+and the entire contents of the directory will be served up at
+``/static/custom``.  If you wish to include content other than static
+files in a theme directory, but do not wish that content to be served up,
+then you can create a sub directory named ``static``. If the theme folder
+contains a sub-directory with the name ``static``, then
+``static/custom/static``` will be used as the root for the content
+served at ``/static/custom``.
 
-If the theme folder (or its static folder) contain an 'img' directory,
-then all images contained within dashboard/img can be overridden by providing
-a file with the same name.  This makes it very easy to customize logo.png,
-logo-splash.png and favicon.ico.
+The static root of the theme folder must always contain a _variables.scss
+file and a _styles.scss file.  These must contain or import all the
+bootstrap and horizon specific variables and styles which are used to style
+the GUI. For example themes, see: /horizon/openstack_dashboard/themes/
 
 
 ``DEFAULT_THEME_PATH``

openstack_dashboard/local/local_settings.py.example

@@ -370,7 +370,7 @@ TIME_ZONE = "UTC"
 
 # Change this patch to the appropriate static directory containing
 # two files: _variables.scss and _styles.scss
-#CUSTOM_THEME_PATH = 'static/themes/default'
+#CUSTOM_THEME_PATH = 'themes/default'
 
 LOGGING = {
     'version': 1,

openstack_dashboard/static/dashboard/scss/components/_navbar.scss

@@ -0,0 +1,4 @@
+.navbar-brand img {
+  max-height: $navbar-height;
+  vertical-align: middle;
+}

openstack_dashboard/static/dashboard/scss/horizon.scss

@@ -16,6 +16,7 @@
 @import "splash";
 @import "components/resource_browser";
 @import "components/sidebar";
+@import "components/navbar";
 @import "components/inline_edit";
 @import "components/charts";
 @import "components/workflow";

openstack_dashboard/themes/default/bootstrap/components/_navbar.scss

@@ -15,10 +15,6 @@ $navbar-dropdown-arrow-offset: $padding-small-horizontal;
     height: 100%;
     vertical-align: middle;
   }
-  img {
-    vertical-align: middle;
-    max-height: $navbar-height;
-  }
 }
 
 .navbar {