[docs] Add a feedback form (#5610)

* Create a feedback form

* feedback

* fix

* fix

* fix

* wording

doc/source/_templates/breadcrumbs.html

@@ -0,0 +1,15 @@
+<!-- Based off https://github.com/edx/edx-documentation/. -->
+<div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    {% block breadcrumbs %}
+      <li><a href="{{ pathto(master_doc) }}" class="icon icon-home"></a> &raquo;</li>
+        {% for doc in parents %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+        {% endfor %}
+      <li>{{ title }}</li>
+    {% endblock %}
+    <li class="wy-breadcrumbs-aside">
+      <a href="{{ feedback_form_url }}" target="_blank">Doc suggestion?</a>
+    </li>
+  </ul>
+<hr/>

doc/source/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+import urllib
 import shlex
 
 # These lines added to enable Sphinx to work without installing Ray.
@@ -330,4 +331,28 @@ texinfo_documents = [
 # Python methods should be presented in source code order
 autodoc_member_order = 'bysource'
 
-# see also http://searchvoidstar.tumblr.com/post/125486358368/making-pdfs-from-markdown-on-readthedocsorg-using
+# Taken from https://github.com/edx/edx-documentation
+FEEDBACK_FORM_FMT = "https://github.com/ray-project/ray/issues/new?title={title}&labels=docs&body={body}"
+
+
+def feedback_form_url(project, page):
+    """Create a URL for feedback on a particular page in a project."""
+    return FEEDBACK_FORM_FMT.format(
+        title=urllib.parse.quote(
+            "[docs] Issue on `{page}.rst`".format(page=page)),
+        body=urllib.parse.quote(
+            "# Documentation Problem/Question/Comment\n"
+            "<!-- Describe your issue/question/comment below. -->\n"
+            "<!-- If there are typos or errors in the docs, feel free to create a pull-request. -->\n"
+            "\n\n\n\n"
+            "(Created directly from the docs)\n"))
+
+
+def update_context(app, pagename, templatename, context, doctree):
+    """Update the page rendering context to include ``feedback_form_url``."""
+    context['feedback_form_url'] = feedback_form_url(app.config.project,
+                                                     pagename)
+
+
+def setup(app):
+    app.connect('html-page-context', update_context)

doc/source/object-store.rst

@@ -117,7 +117,7 @@ Serialization: Numpy Arrays
 ---------------------------
 
 Ray optimizes for numpy arrays by using the `Apache Arrow`_ data format.
-The numpy array is stored as a read-only object, and all Ray workers on the same node can read the numpy array in the object store without copying (zero-copy reads). Each numpy array object in the worker process holds a pointer to the relevant array held in shared memory. Any writes to the read-only object will result in a copy into the local process memory.
+The numpy array is stored as a read-only object, and all Ray workers on the same node can read the numpy array in the object store without copying (zero-copy reads). Each numpy array object in the worker process holds a pointer to the relevant array held in shared memory. Any writes to the read-only object will require the user to first copy it into the local process memory.
 
 There are some advantages to this form of serialization: