[REVIEW] Improve Documentation Examples and Source Linking (#2541)

* Source links working for python code * Missed copybutton.css * Bad commit. Do not use * Source links working for cython. Need to test cyfunction for benchmark performance regressions * Removing accidentally committed file * Adding PR to CHANGELOG * Fixing style issues * Large cleanup of sphinx documentation warnings * Style cleanup * More style cleanup * Fixing doc warnings * Moving the CHANGELOG PR from 0.15 to 0.16 * Adding copyright messages to new files from scikit-learn * Fixing style issues * Fixing lone sphinx warning Co-authored-by: John Zedlewski <[email protected]>
rapidsai · Sep 25, 2020 · 5300ce4 · 5300ce4
1 parent bd65c15
commit 5300ce4
Show file tree

Hide file tree

Showing 9 changed files with 300 additions and 41 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -29,6 +29,7 @@
 - PR #2799: Reenable lightgbm test with lower (1%) proba accuracy
 - PR #2800: Align cuML's spdlog version with RMM's
 - PR #2824: Make data conversions warnings be debug level
+- PR #2541: Improve Documentation Examples and Source Linking
 - PR #2837: Make the FIL node reorder loop more obvious
 - PR #2849: make num_classes significant in FLOAT_SCALAR case
 - PR #2792: Project flash (new build process) script changes

diff --git a/docs/source/_static/copybutton.css b/docs/source/_static/copybutton.css
@@ -0,0 +1,42 @@
+/* This contains code with copyright by the scikit-learn project, subject to
+the license in /thirdparty/LICENSES/LICENSE.scikit_learn */
+
+/* copybutton */
+/* Adds "Show/Hide Output" button to Examples */
+
+.copybutton {
+  cursor: pointer;
+  position: absolute;
+  top: 0px;
+  right: 0px;
+  border: 1px solid rgb(221, 221, 221);
+  color: rgb(221, 221, 221);
+  font-family: monospace;
+  padding-left: 0.2rem;
+  padding-right: 0.2rem;
+}
+
+div.highlight:hover span.copybutton::after {
+  background: #3F556B;
+  border-radius: 0.25rem;
+  color: white;
+  content: attr(title);
+  padding: 0.25rem;
+  position: absolute;
+  z-index: 98;
+  width: 100px;
+  font-size: 0.7rem;
+  top: 0;
+  right: 0;
+}
+
+/* copy buttonn */
+div.highlight:hover span.copybutton {
+  background-color: #3F556B;
+  color: white;
+}
+
+div.highlight:hover span.copybutton:hover {
+  background-color: #20252B;
+}
+
diff --git a/docs/source/_static/example_mod.js b/docs/source/_static/example_mod.js
@@ -0,0 +1,61 @@
+// This contains code with copyright by the scikit-learn project, subject to
+// the license in /thirdparty/LICENSES/LICENSE.scikit_learn
+
+$(document).ready(function () {
+   /* Add a [>>>] button on the top-right corner of code samples to hide
+    * the >>> and ... prompts and the output and thus make the code
+    * copyable. */
+   var div = $('.highlight-python .highlight,' +
+      '.highlight-python3 .highlight,' +
+      '.highlight-pycon .highlight,' +
+      '.highlight-default .highlight')
+   var pre = div.find('pre');
+
+   // get the styles from the current theme
+   pre.parent().parent().css('position', 'relative');
+   var hide_text = 'Hide prompts and outputs';
+   var show_text = 'Show prompts and outputs';
+
+   // create and add the button to all the code blocks that contain >>>
+   div.each(function (index) {
+      var jthis = $(this);
+      if (jthis.find('.gp').length > 0) {
+         var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
+         button.attr('title', hide_text);
+         button.data('hidden', 'false');
+         jthis.prepend(button);
+      }
+      // tracebacks (.gt) contain bare text elements that need to be
+      // wrapped in a span to work with .nextUntil() (see later)
+      jthis.find('pre:has(.gt)').contents().filter(function () {
+         return ((this.nodeType == 3) && (this.data.trim().length > 0));
+      }).wrap('<span>');
+   });
+
+   // define the behavior of the button when it's clicked
+   $('.copybutton').click(function (e) {
+      e.preventDefault();
+      var button = $(this);
+      if (button.data('hidden') === 'false') {
+         // hide the code output
+         button.parent().find('.go, .gp, .gt').hide();
+         button.next('pre')
+            .find('.gt')
+            .nextUntil('.gp, .go')
+            .css('visibility', 'hidden');
+         button.css('text-decoration', 'line-through');
+         button.attr('title', show_text);
+         button.data('hidden', 'true');
+      } else {
+         // show the code output
+         button.parent().find('.go, .gp, .gt').show();
+         button.next('pre')
+            .find('.gt')
+            .nextUntil('.gp, .go')
+            .css('visibility', 'visible');
+         button.css('text-decoration', 'none');
+         button.attr('title', hide_text);
+         button.data('hidden', 'false');
+      }
+   });
+});
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -70,7 +70,7 @@ Feature and Label Encoding (Single-GPU)
  .. autoclass:: cuml.preprocessing.OneHotEncoder
     :members:
 
- .. autoclass:: cuml.preprocessing.TargetEncoder
+ .. autoclass:: cuml.preprocessing.TargetEncoder.TargetEncoder
     :members:
 
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,8 +18,17 @@
 #
 import os
 import sys
+
+# If extensions (or modules to document with autodoc) are in another
+# directory, add these directories to sys.path here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+sys.path.insert(0, os.path.abspath('sphinxext'))
 sys.path.insert(0, os.path.abspath('../../python'))
 
+from github_link import make_linkcode_resolve # noqa
+
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -30,22 +39,27 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.intersphinx',
+    'numpydoc',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'numpydoc',
-    "sphinx_markdown_tables",
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.linkcode',
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
     "nbsphinx",
     "recommonmark",
+    "sphinx_markdown_tables",
 ]
 
 ipython_mplbackend = "str"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# generate autosummary even if no references
+# autosummary_generate = True
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -87,7 +101,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -107,7 +120,6 @@
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
-
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -119,13 +131,13 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_js_files = ["example_mod.js"]
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'cuMLdoc'
 
-
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -150,37 +162,28 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'cuml.tex', 'cuml Documentation',
-     'nvidia', 'manual'),
+    (master_doc, 'cuml.tex', 'cuml Documentation', 'nvidia', 'manual'),
 ]
 
-
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'cuml', 'cuml Documentation',
-     [author], 1)
-]
-
+man_pages = [(master_doc, 'cuml', 'cuml Documentation', [author], 1)]
 
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'cuml', 'cuml Documentation',
-     author, 'cuml', 'One line description of project.',
-     'Miscellaneous'),
+    (master_doc, 'cuml', 'cuml Documentation', author, 'cuml',
+     'One line description of project.', 'Miscellaneous'),
 ]
 
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
 
-
 # Config numpydoc
 numpydoc_show_inherited_class_members = False
 numpydoc_class_members_toctree = False
@@ -190,3 +193,10 @@ def setup(app):
     app.add_css_file('copybutton.css')
     app.add_css_file('params.css')
     app.add_css_file('references.css')
+
+
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve(
+    'cuml', 'https://github.com/rapidsai/'
+    'cuml/blob/{revision}/python/'
+    '{package}/{path}#L{lineno}')