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: c43d442c4d 
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
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/ /openstackdocstheme.egg-info/
*.pyc *.pyc
doc/build doc/build
doc/source/BBresult

23
doc/source/conf.py
View File

@@ -43,19 +43,33 @@ source_suffix = '.rst'
# The master toctree document. # The master toctree document.
master_doc = 'index' master_doc = 'index'
# General information about the project. # "project" contains the name of the book, such as
project = u'os-doc-demo' # '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' copyright = u'2015, OpenStack Contributors'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
# built documents. # built documents.
# #
# "version" and "release" are used by the "log-a-bug" feature
#
# The short X.Y version. # The short X.Y version.
version = '1.0' version = '1.0'
# The full version, including alpha/beta/rc tags. # The full version, including alpha/beta/rc tags.
release = '1.0' 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 # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # for a list of supported languages.
#language = None #language = None
@@ -139,6 +153,11 @@ html_static_path = ['_static/css']
# using the given strftime format. # using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y' #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 # If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities. # typographically correct entities.
#html_use_smartypants = True #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"> <html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head> <head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/> <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
{% block header %}{% endblock %}
<title>OpenStack Docs: {{ title }}</title> <title>OpenStack Docs: {{ title }}</title>
<meta charset="utf-8"> <meta charset="utf-8">
<meta content="IE=edge" http-equiv="X-UA-Compatible"/> <meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta content="width=device-width, initial-scale=1" name="viewport"/> <meta name="viewport" content="width=device-width, initial-scale=1">
<!-- CSS references are in the css.html template --> <!-- CSS references are in the css.html template -->
{% include 'css.html' %} {% include 'css.html' %}
{# FAVICON #} {# FAVICON #}
@@ -46,26 +47,21 @@
<a href="#" class="docs-tag">Conceptual architecture</a> <a href="#" class="docs-tag">Conceptual architecture</a>
</div> --> </div> -->
<div class="row docs-byline bottom"> <div class="row docs-byline bottom">
<div class="docs-browse"> <div class="docs-updated">
{% if next or prev %} updated: {{ last_updated }} | release: {{ release }}
{% 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> </div>
<a href="http://git.openstack.org/" class="docs-edit"> <a href="http://git.openstack.org/" class="docs-edit">
<i class="fa fa-pencil"></i> suggest edits <i class="fa fa-pencil"></i> suggest edits
</a> </a>
</div> </div>
<div class="row"> <div class="row">
<div class="col-lg-8 col-md-8 col-sm-8 docs-license"> <div class="col-lg-8 col-md-8 col-sm-8 docs-license">
{% include 'license_cc.html' %} {% include 'license_cc.html' %}
</div> </div>
<div class="col-lg-4 col-md-4 col-sm-4 docs-actions-wrapper"> <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 <i class="fa fa-bug"></i>found an error? report a bug
</a> </a>
<a href="http://ask.openstack.org" class="docs-footer-actions"> <a href="http://ask.openstack.org" class="docs-footer-actions">
@@ -82,7 +78,9 @@
<!-- Footer --> <!-- Footer -->
{% include 'footer.html' %} {% include 'footer.html' %}
<!-- Scripts in: static directory--> <!-- Scripts in: static directory-->
{% include 'script_footer.html' %} {% include 'script_footer.html' %}
</body> </body>
</html> </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> <script type="text/javascript" src="{{pathto('_static/js/webui-popover.js', 1)}}"></script>
<!-- Javascript for page --> <!-- 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) --> <!-- Javascript for search boxes (both sidebar and top nav) -->
<script type="text/javascript"> <script type="text/javascript">
(function() { (function() {

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

@@ -33,7 +33,7 @@ $(".docs-sidebar-section ol > li > a").click(function () {
}); });
/* Bug #1417291 /* 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. a numbered sublist of a bulleted list.
It's probably there to implement expand/collapse of It's probably there to implement expand/collapse of
list items, but unfortunately it affects also those list items, but unfortunately it affects also those
@@ -94,7 +94,7 @@ $.getJSON('common/js/doc-characters.json', function(data) {
}); });
/* BB 150310 /* 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 and warning. We decorate their title paragraphs with Font Awesome icons
by adding the appropriate FA classes. */ 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'); $('div.warning > p.admonition-title').addClass('fa fa-exclamation-triangle');
/* BB 150310 /* BB 150310
We also insert a space between the icon and the admonition title We also insert a space between the icon and the admonition title
("Note", "Warning", "Important" or their i18n equivalents). ("Note", "Warning", "Important" or their i18n equivalents).
This could be done with a single clause $('p.admonition-title')...., This could be done with a single clause $('p.admonition-title')....,
affecting all types of admonitions. I play it safe here and explicitly affecting all types of admonitions. I play it safe here and explicitly
work on the three openstackdocstheme admonitions. work on the three openstackdocstheme admonitions.
The first parameter of the text() callback is not needed here (it's The first parameter of the text() callback is not needed here (it's
the index of the HTML element that we are modifying) */ the index of the HTML element that we are modifying) */
$('div.important > p.admonition-title').text(function(ignored_para,original) { $('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 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> --> <!-- <a href="#"><i class="fa fa-cloud-download" data-toggle="tooltip" data-placement="top" title="Download PDF"></i></a> -->
<!-- lp bug 1421813 --> <!-- 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> --> <!-- <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 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>
<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>
</div> </div>
</div> </div>
</div> </div>