openstack/openstackdocstheme
Code Issues Proposed changes

"log a bug" link added to Sphinx-based documentation

Browse Source 
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🆔 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
This commit is contained in:
Bernd Bausch 2015-03-01 13:04:09 +09:00 committed by Anne Gentle
parent 40c2c4fdb9
commit 606ec02d4a
6 changed files with 87 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -5,3 +5,4 @@ _build/
/openstackdocstheme.egg-info/
*.pyc
doc/build
doc/source/BBresult

23
doc/source/conf.py
View File

@ -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

24
openstackdocstheme/theme/openstackdocs/layout.html
View File

@ -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>

34
openstackdocstheme/theme/openstackdocs/script_footer.html
View File

@ -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() {

10
openstackdocstheme/theme/openstackdocs/static/js/docs.js
View File

@ -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;
}

3
openstackdocstheme/theme/openstackdocs/titlerow.html
View File

@ -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>