From e974da0a3512e2e38d05b08a70e1dc957efbe7b0 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sat, 16 May 2020 12:12:31 +0200 Subject: [PATCH] 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 | 1 + doc/source/index.rst | 19 ++++++++++++++++ openstackdocstheme/ext.py | 15 +++++++++++++ .../theme/openstackdocs/layout.html | 3 +++ .../theme/openstackdocs/script_footer.html | 4 ++++ .../openstackdocs/static/css/combined.css | 8 +++++++ .../theme/openstackdocs/static/js/docs.js | 22 ++++++++++++++++--- .../theme/openstackdocs/titlerow.html | 3 +++ .../notes/pdf_link-c6b0ed36dd12b0ef.yaml | 7 ++++++ 9 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 releasenotes/notes/pdf_link-c6b0ed36dd12b0ef.yaml diff --git a/doc/source/conf.py b/doc/source/conf.py index e0154cb7..a9596bec 100644 --- a/doc/source/conf.py +++ b/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' diff --git a/doc/source/index.rst b/doc/source/index.rst index ae130883..e8ff84df 100644 --- a/doc/source/index.rst +++ b/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-.pdf`` and placed + in the top-level directory where ```` 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`` diff --git a/openstackdocstheme/ext.py b/openstackdocstheme/ext.py index a77b7034..76714ead 100644 --- a/openstackdocstheme/ext.py +++ b/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') diff --git a/openstackdocstheme/theme/openstackdocs/layout.html b/openstackdocstheme/theme/openstackdocs/layout.html index c1337116..4be5b3f4 100644 --- a/openstackdocstheme/theme/openstackdocs/layout.html +++ b/openstackdocstheme/theme/openstackdocs/layout.html @@ -53,6 +53,9 @@ ga('send', 'pageview'); {% if next %} {% endif %} + {%- if pdf_link %} + + {% endif %} {%- if bug_project %} {% endif %} diff --git a/openstackdocstheme/theme/openstackdocs/script_footer.html b/openstackdocstheme/theme/openstackdocs/script_footer.html index 07047631..4a17bdd8 100644 --- a/openstackdocstheme/theme/openstackdocs/script_footer.html +++ b/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); diff --git a/openstackdocstheme/theme/openstackdocs/static/css/combined.css b/openstackdocstheme/theme/openstackdocs/static/css/combined.css index b39000b0..89d32526 100644 --- a/openstackdocstheme/theme/openstackdocs/static/css/combined.css +++ b/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; diff --git a/openstackdocstheme/theme/openstackdocs/static/js/docs.js b/openstackdocstheme/theme/openstackdocs/static/js/docs.js index bbc8c87d..1a36e708 100644 --- a/openstackdocstheme/theme/openstackdocs/static/js/docs.js +++ b/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; } diff --git a/openstackdocstheme/theme/openstackdocs/titlerow.html b/openstackdocstheme/theme/openstackdocs/titlerow.html index a7845c0d..c7ba69b8 100644 --- a/openstackdocstheme/theme/openstackdocs/titlerow.html +++ b/openstackdocstheme/theme/openstackdocs/titlerow.html @@ -25,6 +25,9 @@ {% if next %} {% endif %} + {%- if pdf_link %} + + {% endif %} {%- if bug_project %} {% endif %} diff --git a/releasenotes/notes/pdf_link-c6b0ed36dd12b0ef.yaml b/releasenotes/notes/pdf_link-c6b0ed36dd12b0ef.yaml new file mode 100644 index 00000000..a9195a3f --- /dev/null +++ b/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``.