[Docs] use openstack theme outside rtd

Rally team posts documentation at two places:
- http://rally.readthedocs.org/en/latest/ (preferable place)
- http://docs.openstack.org/developer/rally/

Most projects post docs at docs.o.o with oslosphinx theme. Since default
theme of sphinx is not so good, let's use official openstack theme instead.

Theme from oslosphinx has several issues:
- it is hard to find the link to home page of project documentation
- there is no sidebar with global content

Based on these two issues let's extend oslosphinx theme a bit.

Change-Id: Ifc75b430b7335c6a87a9102810ec33a5a913c43a

doc/source/_templates/openstackrally/_static/img.css

@@ -0,0 +1,3 @@
+.body img {
+    max-width: 100%;
+}

doc/source/_templates/openstackrally/layout.html

@@ -0,0 +1,47 @@
+{% extends "openstack/layout.html" %}
+{% set show_source = False %}
+{% set css_files = css_files + ["_static/img.css"] %}
+
+{# sidebarlogo is a top block in sidebar. Let's use it to display home link #}
+{%- block sidebarlogo %}
+    <h3><a href="{{ pathto(master_doc) }}">What is Rally?</a></h3>
+{%- endblock %}
+
+{# Display global toc instead of local #}
+{%- block sidebartoc %}
+    <h3>Contents</h3>
+    {{ toctree() }}
+{%- endblock %}
+
+{# Turn off sections "Previous topic" and "Next topic" #}
+{%- block sidebarrel %}{% endblock %}
+
+{% block projectsource %}
+    <h3>Contacts</h3>
+    <p class="topless" style="color: black">
+        <b>IRC</b> <br /><a href="ircs://irc.freenode.net:6697/#openstack-rally">#openstack-rally</a> channel at FreeNode<br />
+        <b>E-mail</b> <br /><a href="mailto:openstack-dev@lists.openstack.org?subject=[Rally]">openstack-dev@lists.openstack.org</a> with "[Rally]" tag in subject
+    </p>
+    <h3>Useful links</h3>
+    <ul>
+        <li><a href="{{ pathto(master_doc) }}">Documentation</a></li>
+        <li><a href="http://rally.readthedocs.org/en/latest/">Documentation at RTD</a></li>
+        <li><a href="http://git.openstack.org/cgit/openstack/rally">Source</a></li>
+        <li><a href="https://github.com/openstack/rally">GitHub mirror</a></li>
+        <li><a href="http://bugs.launchpad.net/rally">Bug tracker</a></li>
+        <li><a href="https://docs.google.com/a/mirantis.com/spreadsheets/d/16DXpfbqvlzMFaqaXAcJsBzzpowb_XpymaK2aFY2gA2g">RoadMap</a></li>
+        <li><a href="https://launchpad.net/rally">Launchpad page</a></li>
+    </ul>
+{% endblock %}
+
+{# copy-pasted from original theme and extended with Rally links #}
+{%- block header_navigation %}
+<li><a href="http://www.openstack.org/" title="Go to the Home page" class="link">Home</a></li>
+<li><a href="http://www.openstack.org/projects/" title="Go to the Projects page">Projects</a></li>
+<li><a href="http://www.openstack.org/user-stories/" title="Go to the User Stories page" class="link">User Stories</a></li>
+<li><a href="http://www.openstack.org/community/" title="Go to the Community page" class="link">Community</a></li>
+<li><a href="http://www.openstack.org/blog/" title="Go to the OpenStack Blog">Blog</a></li>
+<li><a href="http://wiki.openstack.org/" title="Go to the OpenStack Wiki">Wiki</a></li>
+<li><a href="{{ pathto(master_doc) }}" title="Go to Rally Documentation" class="current">Documentation</a></li>
+{% endblock %}
+

doc/source/_templates/openstackrally/theme.conf

@@ -0,0 +1,2 @@
+[theme]
+inherit = openstack

doc/source/conf.py

@@ -34,6 +34,8 @@ sys.path.insert(0, os.path.abspath('./'))
 
 # -- General configuration ----------------------------------------------------
 
+on_rtd = os.environ.get('READTHEDOCS') == 'True'
+
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = "1.0"
 
@@ -122,22 +124,29 @@ pygments_style = "sphinx"
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
-
+if not on_rtd:
+    html_theme = "openstackrally"
+else:
+    html_theme = "default"
 # 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
 # documentation.
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+if not on_rtd:
+    import oslosphinx
+    theme_dir = os.path.join(os.path.dirname(oslosphinx.__file__), 'theme')
+    html_theme_path = [theme_dir, "_templates"]
+else:
+    html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 # html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+# html_short_title = None
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -151,14 +160,17 @@ html_theme = "default"
 # 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 = []
+if not on_rtd:
+    html_static_path = ["_templates/openstackrally/_static"]
+else:
+    html_static_path = []
 
 # If not "", a "Last updated on:" timestamp is inserted at every page bottom,
 # using the given strftime format.
-git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
-    "-n1"]
-html_last_updated_fmt = subprocess.Popen(git_cmd,
-                                     stdout=subprocess.PIPE).communicate()[0]
+git_cmd = [
+    "git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", "-n1"]
+html_last_updated_fmt = subprocess.Popen(
+        git_cmd, stdout=subprocess.PIPE).communicate()[0]
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.