Merge pull request canonical#12 from s-makin/feedback-button

Add docs feedback button

.sphinx/_static/github_issue_links.css

@@ -0,0 +1,24 @@
+.github-issue-link-container {
+    padding-right: 0.5rem;
+}
+.github-issue-link {
+    font-size: var(--font-size--small);
+    font-weight: bold;
+    background-color: #DD4814;
+    padding: 13px 23px;
+    text-decoration: none;
+}
+.github-issue-link:link {
+    color: #FFFFFF;
+}
+.github-issue-link:visited {
+    color: #FFFFFF
+}
+.muted-link.github-issue-link:hover {
+    color: #FFFFFF;
+    text-decoration: underline;
+}
+.github-issue-link:active {
+    color: #FFFFFF;
+    text-decoration: underline;
+}

.sphinx/_static/github_issue_links.js

@@ -0,0 +1,26 @@
+window.onload = function() {
+    const link = document.createElement("a");
+    link.classList.add("muted-link");
+    link.classList.add("github-issue-link");
+    link.text = "Give feedback";
+    link.href = (
+        github_url
+        + "/issues/new?"
+        + "title=docs%3A+TYPE+YOUR+QUESTION+HERE"
+        + "&body=*Please describe the question or issue you're facing with "
+        + `"${document.title}"`
+        + ".*"
+        + "%0A%0A%0A%0A%0A"
+        + "---"
+        + "%0A"
+        + `*Reported+from%3A+${location.href}*`
+    );
+    link.target = "_blank";
+
+    const div = document.createElement("div");
+    div.classList.add("github-issue-link-container");
+    div.append(link)
+
+    const container = document.querySelector(".article-container > .content-icon-container");
+    container.prepend(div);
+};

.sphinx/_templates/base.html

@@ -0,0 +1,7 @@
+{% extends "furo/base.html" %}
+
+{% block theme_scripts %}
+<script>
+  const github_url = "{{ github_url }}";
+</script>
+{% endblock theme_scripts %}

conf.py

@@ -128,8 +128,13 @@
 
 html_static_path = ['.sphinx/_static']
 html_css_files = [
-    'custom.css'
+    'custom.css',
+    'github_issue_links.css',
 ]
+html_js_files = [
+    'github_issue_links.js',
+]
+
 
 # Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
 # For example: "explanation/old-name.html": "../how-to/prettify.html",

readme.rst

@@ -38,7 +38,7 @@ The documentation will be available at `127.0.0.1:8000 <http://127.0.0.1:8000>`_
 
 The command:
 
-* activates the virtual environment and start serving the documentation
+* activates the virtual environment and starts serving the documentation
 * rebuilds the documentation each time you save a file
 * sends a reload page signal to the browser when the documentation is rebuilt
 
@@ -64,7 +64,7 @@ In ``conf.py``, you will need to check or edit several settings in the *Project
 In the ``html_context`` variable, update the following settings:
 
 * ``discourse_prefix`` - the URL to the Discourse instance your project uses (needed to add links to posts using the ``:discourse:`` metadata at the top of a file)
-* ``github_url`` - the link to your GitHub repository (needed to create the Edit link in the footer)
+* ``github_url`` - the link to your GitHub repository (needed to create the Edit link in the footer and the feedback button)
 * ``github_version`` - the branch that contains this version of the documentation
 * ``github_folder`` - the folder that contains the documentation files
 * ``github_filetype`` - the file type of the documentation files (usually ``rst`` or ``md``)
@@ -85,4 +85,19 @@ repository.)
 Configure the link check
 ------------------------
 
-If you have links in the documentation that you don't want to be checked (for example, because they are local links or give random errors even though they work), you can add them to the ``linkcheck_ignore`` variable in the ``conf.py`` file.
+If you have links in the documentation that you don't want to be checked (for
+example, because they are local links or give random errors even though they
+work), you can add them to the ``linkcheck_ignore`` variable in the ``conf.py``
+file.
+
+Activate/deactivate feedback button
+-----------------------------------
+
+A feedback button is included by default, which appears at the top of each page
+in the documentation. It redirects users to your GitHub issues page, and
+populates an issue for them with details of the page they were on when they
+clicked the button. 
+
+If your project does not use GitHub issues, or you don't want the feedback
+button for another reason, you can deactivate the button by removing the
+``github_issue_links.js`` script from the ``conf.py`` file.