From 606ec02d4a1b22cd5e4f05669eaa3756d5e4f8ed Mon Sep 17 00:00:00 2001
From: Bernd Bausch <berndbausch@gmail.com>
Date: Sun, 1 Mar 2015 13:04:09 +0900
Subject: [PATCH] "log a bug" link added to Sphinx-based documentation

Current documentation is Docbook-based. Each page features two
"log a bug" links near the top and the bottom. This bug fix
modifies the openstackdocstheme to do something
similar for future Sphinx-based documentation pages.

Regarding functionality:
------------------------
In the current DocBook-based implementation, a click on
"log a bug" opens a launchpad page with the bug summary and
further information prepopulated. Summary is the name of the
book, such as "Install Guide for Ubuntu - Icehouse"; an example for
Further Information is:

    -----------------------------------
    Built: 2015-01-06T17:15:01 00:00
    git SHA: 233c8098bbdc5bc83bbd74403650feb6610f4b95
    URL:
    http://docs.openstack.org/icehouse/install-guide/install/apt/content/
    source File:
    file:/home/jenkins/workspace/openstack-manuals-tox-doc-publishdocs/doc/install-guide/bk_openstackinstallguide.xml
    xml:id: openstack-install-manual-icehouse

With our Sphinx-based docs, the Release value, git SHA, and source file should be sufficient. Here is the new functionality:


-------------------------------------
Release: 1.0 on 2015-04-06 12:27
SHA: c43d442c4d053891a22bde1232f9fbea18bad44e
Source: http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/source/index.rst

Change-Id: Ib60146d993ff67fc3f8fd8703cdad1935f7ec6bb
Partial-Bug: #1421799
---
 .gitignore                                    |  1 +
 doc/source/conf.py                            | 23 +++++++++++--
 .../theme/openstackdocs/layout.html           | 24 ++++++-------
 .../theme/openstackdocs/script_footer.html    | 34 +++++++++++++++++++
 .../theme/openstackdocs/static/js/docs.js     | 28 ++++++++++-----
 .../theme/openstackdocs/titlerow.html         |  3 +-
 6 files changed, 87 insertions(+), 26 deletions(-)

diff --git a/.gitignore b/.gitignore
index 4dd38514..4d57995e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ _build/
 /openstackdocstheme.egg-info/
 *.pyc
 doc/build
+doc/source/BBresult
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 5b57504a..1d64ef3d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -43,19 +43,33 @@ source_suffix = '.rst'
 # The master toctree document.
 master_doc = 'index'
 
-# General information about the project.
-project = u'os-doc-demo'
+# "project" contains the name of the book, such as
+# 'security guide' or 'network guide'
+# It's used by the "log-a-bug" button on each page
+# and should ultimately be set automatically by the build process
+project = u'network guide'
 copyright = u'2015, OpenStack Contributors'
 
 # 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.
 #
+# "version" and "release" are used by the "log-a-bug" feature
+#
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
 release = '1.0'
 
+# We ask git for the SHA checksum
+# The git SHA checksum is used by "log-a-bug"
+git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
+gitsha = os.popen(git_cmd).read().strip('\n')
+# source tree
+pwd = os.popen("pwd").read().strip('\n')
+# html_context allows us to pass arbitrary values into the html template
+html_context = { "pwd":pwd, "gitsha":gitsha }
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
@@ -139,6 +153,11 @@ html_static_path = ['_static/css']
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
 
+# So that we can enable "log-a-bug" links from each output HTML page, this
+# variable must be set to a format that includes year, month, day, hours and
+# minutes.
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
diff --git a/openstackdocstheme/theme/openstackdocs/layout.html b/openstackdocstheme/theme/openstackdocs/layout.html
index 689c2a1d..240939e9 100644
--- a/openstackdocstheme/theme/openstackdocs/layout.html
+++ b/openstackdocstheme/theme/openstackdocs/layout.html
@@ -2,10 +2,11 @@
 <html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
   <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
+{% block header %}{% endblock %}
   <title>OpenStack Docs: {{ title }}</title>
     <meta charset="utf-8">
-    <meta content="IE=edge" http-equiv="X-UA-Compatible"/>
-    <meta content="width=device-width, initial-scale=1" name="viewport"/>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
 <!-- CSS references are in the css.html template -->
 {% include 'css.html' %}
   {# FAVICON #}
@@ -46,26 +47,21 @@
                 <a href="#" class="docs-tag">Conceptual architecture</a>
             </div> -->
                 <div class="row docs-byline bottom">
-                <div class="docs-browse">
-                {% if next or prev %}
-                    {% if next %}
-                    <a class="docs-edit" href="{{ next.link|e }}">&nbsp;next</a>
-                    {% endif %}
-                    {% if prev %}
-                    <a class="docs-edit" href="{{ prev.link|e }}">previous | </a>
-                    {% endif %}
-                {% endif %}
+                <div class="docs-updated">
+                updated: {{ last_updated }} | release: {{ release }}
                 </div>
                 <a href="http://git.openstack.org/" class="docs-edit">
                     <i class="fa fa-pencil"></i> suggest edits
                 </a>
-                </div>
+</div>
     <div class="row">
          <div class="col-lg-8 col-md-8 col-sm-8 docs-license">
            {% include 'license_cc.html' %}
          </div>
          <div class="col-lg-4 col-md-4 col-sm-4 docs-actions-wrapper">
-                    <a href="#" class="docs-footer-actions">
+                    <!-- ID buglinkbottom added so that pre-filled doc bugs
+                    are sent to Launchpad projects related to the document -->
+                    <a href="#" id="logABugLink2" class="docs-footer-actions">
                         <i class="fa fa-bug"></i>found an error? report a bug
                     </a>
                     <a href="http://ask.openstack.org" class="docs-footer-actions">
@@ -82,7 +78,9 @@
 
     <!-- Footer -->
 {% include 'footer.html' %}
+
 <!-- Scripts in: static directory-->
 {% include 'script_footer.html' %}
+
  </body>
 </html>
diff --git a/openstackdocstheme/theme/openstackdocs/script_footer.html b/openstackdocstheme/theme/openstackdocs/script_footer.html
index 8f1ac845..0a500ecd 100644
--- a/openstackdocstheme/theme/openstackdocs/script_footer.html
+++ b/openstackdocstheme/theme/openstackdocs/script_footer.html
@@ -14,6 +14,40 @@
     <script type="text/javascript" src="{{pathto('_static/js/webui-popover.js', 1)}}"></script>
 
     <!-- Javascript for page -->
+    <script language="JavaScript">
+    /* build a description of this page including SHA, source location on git repo and
+       build time and set the HREF of the bug buttons */
+
+        var lineFeed = "%0A";
+
+        {%- if show_source and has_source and sourcename %}
+            /* for some reason, sphinx replaces the rst extension with
+               a txt one. Replace it back.                          */
+            var sourceFile = "{{ pathto(sourcename,1) }}".replace(/\.txt$/,".rst")
+
+            /* Using the current working directory, figure out
+               in which book we are and use that information to
+               build a link to the source file on git.openstack.ort */
+            var pwd = "{{ pwd }}"
+            var gitlink = "Source: http://git.openstack.org/cgit/openstack/openstack-manuals/tree"
+            gitlink += pwd.slice(pwd.lastIndexOf("/doc/")) + "/" + sourceFile
+        {%- endif %}
+
+        /* gitsha and project rely on variables in conf.py */
+        var gitSha = "SHA: {{ gitsha }}"
+        var bugTitle = "{{ title }} in {{ project }}"
+
+        /* "last_updated" is the build date and time. It relies on the
+           conf.py variable "html_last_updated_fmt", which should include
+           year/month/day as well as hours and minutes                   */
+        var buildstring = "Release: {{ release }} on {{ last_updated }}"
+
+        var fieldComment = encodeURI(buildstring) +
+                           lineFeed + encodeURI(gitSha) +
+                           lineFeed + encodeURI(gitlink)
+
+        logABug(bugTitle, fieldComment)
+    </script>
     <!-- Javascript for search boxes (both sidebar and top nav) -->
 <script type="text/javascript">
         (function() {
diff --git a/openstackdocstheme/theme/openstackdocs/static/js/docs.js b/openstackdocstheme/theme/openstackdocs/static/js/docs.js
index 9ea4b625..d0a54ba6 100644
--- a/openstackdocstheme/theme/openstackdocs/static/js/docs.js
+++ b/openstackdocstheme/theme/openstackdocs/static/js/docs.js
@@ -33,7 +33,7 @@ $(".docs-sidebar-section ol > li > a").click(function () {
 });
 
 /* Bug #1417291
-   The rule below creates a shaded plus sign next to 
+   The rule below creates a shaded plus sign next to
    a numbered sublist of a bulleted list.
    It's probably there to implement expand/collapse of
    list items, but unfortunately it affects also those
@@ -94,7 +94,7 @@ $.getJSON('common/js/doc-characters.json', function(data) {
 });
 
 /* BB 150310
-   openstackdocstheme provides three types of admonitions, important, note 
+   openstackdocstheme provides three types of admonitions, important, note
    and warning. We decorate their title paragraphs with Font Awesome icons
    by adding the appropriate FA classes.                               */
 
@@ -103,14 +103,14 @@ $('div.note > p.admonition-title').addClass('fa fa-check-circle');
 $('div.warning > p.admonition-title').addClass('fa fa-exclamation-triangle');
 
 /* BB 150310
-   We also insert a space between the icon and the admonition title 
-   ("Note", "Warning", "Important" or their i18n equivalents).    
+   We also insert a space between the icon and the admonition title
+   ("Note", "Warning", "Important" or their i18n equivalents).
 
-   This could be done with a single clause $('p.admonition-title')...., 
-   affecting all types of admonitions. I play it safe here and explicitly 
-   work on the three openstackdocstheme admonitions.                           
-   
-   The first parameter of the text() callback is not needed here (it's 
+   This could be done with a single clause $('p.admonition-title')....,
+   affecting all types of admonitions. I play it safe here and explicitly
+   work on the three openstackdocstheme admonitions.
+
+   The first parameter of the text() callback is not needed here (it's
    the index of the HTML element that we are modifying)                 */
 
 $('div.important > p.admonition-title').text(function(ignored_para,original) {
@@ -123,3 +123,13 @@ $('div.warning > p.admonition-title').text(function(ignored_para,original) {
     return " "+original
 });
 
+// Gives the log a bug icon the information it needs to generate the bug in
+// Launchpad with pre-filled information such as git SHA, git.openstack.org
+// source URL, and published document URL.
+function logABug(bugTitle, fieldComment) {
+    var lineFeed = "%0A";
+    var urlBase = "https://bugs.launchpad.net/openstack-manuals/+filebug?field.title="
+    var bugLink = urlBase  + encodeURIComponent(bugTitle) + "&field.comment=" + lineFeed + lineFeed + "-----------------------------------" + lineFeed + fieldComment;
+   document.getElementById("logABugLink1").href=bugLink;
+   document.getElementById("logABugLink2").href=bugLink;
+}
diff --git a/openstackdocstheme/theme/openstackdocs/titlerow.html b/openstackdocstheme/theme/openstackdocs/titlerow.html
index 1d0a5cec..44aace6b 100644
--- a/openstackdocstheme/theme/openstackdocs/titlerow.html
+++ b/openstackdocstheme/theme/openstackdocs/titlerow.html
@@ -13,8 +13,7 @@
                     <!-- <a href="#"><i class="fa fa-cloud-download" data-toggle="tooltip" data-placement="top" title="Download PDF"></i></a> -->
                     <!-- lp bug 1421813 -->
                     <!-- <a href="#"><i class="fa fa-info-circle" data-toggle="tooltip" data-placement="top" title="Toggle Definitions" id="toggle-definitions"></i></a> -->
-                        <!-- Need a more specific link, lp bug 1421814-->
-                        <a href="http://bugs.launchpad.net/openstack-manuals"><i class="fa fa-bug" data-toggle="tooltip" data-placement="top" title="Report a Bug"></i></a>
+                        <a id="logABugLink1" href="" target="_blank" title="Found an error? Report a bug against this page"><i class="fa fa-bug" data-toggle="tooltip" data-placement="top" title="Report a Bug"></i></a>
                     </div>
                 </div>
             </div>