Merge "Add link to PDF file"

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

@@ -197,6 +197,19 @@ def _html_page_context(app, pagename, templatename, context, doctree):
             _html_context_data['bug_tag'] = bug_tag
             logger.debug('[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.debug(
             '[openstackdocstheme] series %r', _html_context_data['series'],
@@ -468,6 +481,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("logABugLink2").href=bugLink;
-    document.getElementById("logABugLink3").href=bugLink;
+    document.getElementById("logABugLink1").href = bugLink;
+    document.getElementById("logABugLink2").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``.