Add link to PDF file

Create new config options to optionally link to a generate PDF file that
is published at the same location as the html files.

Note that the preview will not be able to download the file since
the file is in a different location. The publishing job moves the PDF
file in the top-level directory.

Change-Id: I3ff74030195b6a85ff4e4e3b62f367aa78f85b0a

doc/source/conf.py

@@ -13,6 +13,7 @@ extensions = ['openstackdocstheme']
 openstackdocs_repo_name = 'openstack/openstackdocstheme'
 openstackdocs_bug_project = 'openstack-doc-tools'
 openstackdocs_bug_tag = 'openstackdocstheme'
+openstackdocs_pdf_link = True
 
 # The suffix of source filenames.
 source_suffix = '.rst'

doc/source/index.rst

@@ -111,6 +111,25 @@ Using the theme
    ``openstackdocs_auto_name`` option to ``false`` and configuring the
    ``project`` option to the name you wish to use.
 
+#. (Optional) Link to the PDF file.
+
+   If you build a PDF file as well, the theme can create a link to it.
+   Set ``openstack_pdf_link`` to ``True`` to generate the link.
+   The file is expected to be named ``doc-<shortname>.pdf`` and placed
+   in the top-level directory where ``<shortname>`` is the
+   ``openstackdocs_repo_name``. For example with::
+
+     openstackdocs_repo_name = "openstack/python-glanceclient"
+
+   the shortname is ``python-glanceclient`` and the filename will be
+   ``doc-python-glanceclient.pdf``. Use the variable
+   ``openstackdocs_pdf_filename`` to override the generated file name.
+
+.. versionchanged:: 2.2.0
+
+   The config options ``openstack_pdf_link`` and
+   ``openstackdocs_pdf_filename`` were introduced.
+
 .. versionchanged:: 2.1.0
 
    The ``repository_name``, ``bug_project``, ``bug_tag`` and ``use_storyboard``

openstackdocstheme/ext.py

@@ -186,6 +186,19 @@ def _html_page_context(app, pagename, templatename, context, doctree):
             _html_context_data['bug_tag'] = bug_tag
             logger.info('[openstackdocstheme] bug_tag %r', bug_tag)
 
+        _html_context_data['pdf_link'] = app.config.openstackdocs_pdf_link
+        logger.info('[openstackdocstheme] pdf_link %r',
+                    _html_context_data['pdf_link'])
+        if app.config.openstackdocs_pdf_filename:
+            _html_context_data['pdf_filename'] = (
+                app.config.openstackdocs_pdf_filename)
+        else:
+            short_repo_name = repo_name.split('/')[-1]
+            _html_context_data['pdf_filename'] = f'doc-{short_repo_name}.pdf'
+        if _html_context_data['pdf_link']:
+            logger.info('[openstackdocstheme] pdf_filename %r',
+                        _html_context_data['pdf_filename'])
+
         _html_context_data['series'] = _get_series_name()
         logger.info('[openstackdocstheme] series %r',
                     _html_context_data['series'])
@@ -428,6 +441,8 @@ def setup(app):
     app.add_config_value('openstackdocs_use_storyboard', False, 'env')
     app.add_config_value('openstackdocs_auto_version', None, 'env')
     app.add_config_value('openstackdocs_auto_name', True, 'env')
+    app.add_config_value('openstackdocs_pdf_link', False, 'env')
+    app.add_config_value('openstackdocs_pdf_filename', None, 'env')
 
     # legacy config options
     app.add_config_value('repository_name', None, 'env')

openstackdocstheme/theme/openstackdocs/layout.html

@@ -53,6 +53,9 @@ ga('send', 'pageview');
           {% if next %}
             <a href="{{ next.link|e }}"><i class="fa fa-angle-double-right" data-toggle="tooltip" data-placement="top" title="Next: {{ next.title|striptags }}"></i></a>
           {% endif %}
+          {%- if pdf_link %}
+          <a id="pdfLink2" href="" target="_blank" title="Download the manuals as PDF"><i class="fa fa-file-pdf-o" data-toggle="tooltip" data-placement="top" title="Download PDF"></i></a>
+          {% endif %}
           {%- if bug_project %}
             <a id="logABugLink3" 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>
           {% endif %}

openstackdocstheme/theme/openstackdocs/script_footer.html

@@ -77,4 +77,8 @@
                        lineFeed + encodeURI(gitURL) ;
 
     logABug(bugTitle, bugProject, fieldComment, fieldTags, repositoryName, useStoryboard);
+
+    var currentSourceFile = "{{ pagename }}";
+    var pdfFileName = "{{ pdf_filename }}";
+    pdfLink(currentSourceFile, pdfFileName);
 </script>

openstackdocstheme/theme/openstackdocs/static/css/combined.css

@@ -650,6 +650,14 @@ a.docs-sidebar-section-title:hover {
 .docs-actions .fa-bug:hover {
   color: #9A201D; }
 
+.docs-actions .fa-file-pdf-o {
+  border-left: 1px solid #dae5ee;
+  color: #DA422F;
+  padding: 0 10px; }
+
+.docs-actions .fa-file-pdf-o:hover {
+  color: #9A201D; }
+
 .docs-actions .fa-angle-double-left {
   border-left: 1px solid #dae5ee;
   color: #DA422F;

openstackdocstheme/theme/openstackdocs/static/js/docs.js

@@ -61,7 +61,23 @@ function logABug(bugTitle, bugProject, fieldComment, fieldTags, repositoryName,
         bugChecklist + lineFeed + "-----------------------------------" + lineFeed + fieldComment +
         lineFeed + currentURL;
     }
-    document.getElementById("logABugLink1").href=bugLink;
+    document.getElementById("logABugLink1").href = bugLink;
-    document.getElementById("logABugLink2").href=bugLink;
+    document.getElementById("logABugLink2").href = bugLink;
-    document.getElementById("logABugLink3").href=bugLink;
+    document.getElementById("logABugLink3").href = bugLink;
+}
+
+function pdfLink(currentSourceFile, pdfFileName) {
+    /* Create link to PDF file which is in top-level of document.  */
+
+    /* We know the local path of the html page, so substitute that in
+       the URL with the path to the PDF file. */
+    /* We do not want any #subanchors, so do not use window.location.href. */
+    var currentLink = window.location.protocol + "//" + window.location.hostname + "/" + window.location.pathname;
+    if (currentLink.endsWith("/")) {
+        currentLink = currentLink + "index.html";
+    }
+    var file = currentSourceFile + ".html";
+    var pdfLink = currentLink.replace(file, pdfFileName);
+    document.getElementById("pdfLink1").href = pdfLink;
+    document.getElementById("pdfLink2").href = pdfLink;
 }

openstackdocstheme/theme/openstackdocs/titlerow.html

@@ -25,6 +25,9 @@
     {% if next %}
     <a href="{{ next.link|e }}"><i class="fa fa-angle-double-right" data-toggle="tooltip" data-placement="top" title="Next: {{ next.title|striptags }}"></i></a>
     {% endif %}
+    {%- if pdf_link %}
+    <a id="pdfLink1" href="" target="_blank" title="Download the manuals as PDF"><i class="fa fa-file-pdf-o" data-toggle="tooltip" data-placement="top" title="Download PDF"></i></a>
+    {% endif %}
     {%- if bug_project %}
     <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>
     {% endif %}

releasenotes/notes/pdf_link-c6b0ed36dd12b0ef.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    The theme can now include links on each page to a PDF file. Set
+    the new config option ``openstackdocs_pdf_link`` to enable it
+    and configure the file name if needed with the new config
+    option ``openstackdocs_pdf_filename``.