From ab41864f91713b450695babd5c1424622cb57a54 Mon Sep 17 00:00:00 2001
From: noelsmith <mail@noelsmith.com>
Date: Tue, 29 Sep 2015 13:24:42 -0700
Subject: [PATCH] [SPARK-10415] [PYSPARK] [MLLIB] [DOCS] Enhance Navigation
Sidebar in PySpark API
These are CSS/JavaScript changes changes to make navigation in the PySpark API a bit simpler by adding the following to the sidebar:
* Classes
* Functions
* Tags to highlight experimental features
Online example here: https://dl.dropboxusercontent.com/u/20821334/pyspark-api-nav-enhance/pyspark.mllib.html
(The contribution is my original work and that I license the work to the project under the project's open source license)
Author: noelsmith <mail@noelsmith.com>
Closes #8571 from noel-smith/pyspark-api-nav-enhance.
---
python/docs/_static/pyspark.css | 90 +++++++++++++++++++++++++++
python/docs/_static/pyspark.js | 99 ++++++++++++++++++++++++++++++
python/docs/_templates/layout.html | 6 ++
python/docs/conf.py | 4 +-
4 files changed, 197 insertions(+), 2 deletions(-)
create mode 100644 python/docs/_static/pyspark.css
create mode 100644 python/docs/_static/pyspark.js
create mode 100644 python/docs/_templates/layout.html
diff --git a/python/docs/_static/pyspark.css b/python/docs/_static/pyspark.css
new file mode 100644
index 0000000000..41106f2f6e
--- /dev/null
+++ b/python/docs/_static/pyspark.css
@@ -0,0 +1,90 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+body {
+ background-color: #ffffff;
+}
+
+div.sphinxsidebar {
+ width: 274px;
+}
+
+div.bodywrapper {
+ margin: 0 0 0 274px;
+}
+
+div.sphinxsidebar ul {
+ margin-right: 10px;
+}
+
+div.sphinxsidebar li a {
+ word-break: break-all;
+}
+
+span.pys-tag {
+ font-size: 11px;
+ font-weight: bold;
+ margin: 0 0 0 2px;
+ padding: 1px 3px 1px 3px;
+ -moz-border-radius: 3px;
+ -webkit-border-radius: 3px;
+ border-radius: 3px;
+ text-align: center;
+ text-decoration: none;
+}
+
+span.pys-tag-experimental {
+ background-color: rgb(37, 112, 128);
+ color: rgb(255, 255, 255);
+}
+
+span.pys-tag-deprecated {
+ background-color: rgb(238, 238, 238);
+ color: rgb(62, 67, 73);
+}
+
+div.pys-note-experimental {
+ background-color: rgb(88, 151, 165);
+ border-color: rgb(59, 115, 127);
+ color: rgb(255, 255, 255);
+}
+
+div.pys-note-deprecated {
+}
+
+.hasTooltip {
+ position:relative;
+}
+.hasTooltip span {
+ display:none;
+}
+
+.hasTooltip:hover span.tooltip {
+ display: inline-block;
+ -moz-border-radius: 2px;
+ -webkit-border-radius: 2px;
+ border-radius: 2px;
+ background-color: rgb(250, 250, 250);
+ color: rgb(68, 68, 68);
+ font-weight: normal;
+ box-shadow: 1px 1px 3px rgb(127, 127, 127);
+ position: absolute;
+ padding: 0 3px 0 3px;
+ top: 1.3em;
+ left: 14px;
+ z-index: 9999
+}
diff --git a/python/docs/_static/pyspark.js b/python/docs/_static/pyspark.js
new file mode 100644
index 0000000000..75e4c42492
--- /dev/null
+++ b/python/docs/_static/pyspark.js
@@ -0,0 +1,99 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+$(function (){
+
+ function startsWith(s, prefix) {
+ return s && s.indexOf(prefix) === 0;
+ }
+
+ function buildSidebarLinkMap() {
+ var linkMap = {};
+ $('div.sphinxsidebar a.reference.internal').each(function (i,a) {
+ var href = $(a).attr('href');
+ if (startsWith(href, '#module-')) {
+ var id = href.substr(8);
+ linkMap[id] = [$(a), null];
+ }
+ })
+ return linkMap;
+ };
+
+ function getAdNoteDivs(dd) {
+ var noteDivs = {};
+ dd.find('> div.admonition.note > p.last').each(function (i, p) {
+ var text = $(p).text();
+ if (!noteDivs.experimental && startsWith(text, 'Experimental')) {
+ noteDivs.experimental = $(p).parent();
+ }
+ if (!noteDivs.deprecated && startsWith(text, 'Deprecated')) {
+ noteDivs.deprecated = $(p).parent();
+ }
+ });
+ return noteDivs;
+ }
+
+ function getParentId(name) {
+ var last_idx = name.lastIndexOf('.');
+ return last_idx == -1? '': name.substr(0, last_idx);
+ }
+
+ function buildTag(text, cls, tooltip) {
+ return '<span class="pys-tag ' + cls + ' hasTooltip">' + text + '<span class="tooltip">'
+ + tooltip + '</span></span>'
+ }
+
+
+ var sidebarLinkMap = buildSidebarLinkMap();
+
+ $('dl.class, dl.function').each(function (i,dl) {
+
+ dl = $(dl);
+ dt = dl.children('dt').eq(0);
+ dd = dl.children('dd').eq(0);
+ var id = dt.attr('id');
+ var desc = dt.find('> .descname').text();
+ var adNoteDivs = getAdNoteDivs(dd);
+
+ if (id) {
+ var parent_id = getParentId(id);
+
+ var r = sidebarLinkMap[parent_id];
+ if (r) {
+ if (r[1] === null) {
+ r[1] = $('<ul/>');
+ r[0].parent().append(r[1]);
+ }
+ var tags = '';
+ if (adNoteDivs.experimental) {
+ tags += buildTag('E', 'pys-tag-experimental', 'Experimental');
+ adNoteDivs.experimental.addClass('pys-note pys-note-experimental');
+ }
+ if (adNoteDivs.deprecated) {
+ tags += buildTag('D', 'pys-tag-deprecated', 'Deprecated');
+ adNoteDivs.deprecated.addClass('pys-note pys-note-deprecated');
+ }
+ var li = $('<li/>');
+ var a = $('<a href="#' + id + '">' + desc + '</a>');
+ li.append(a);
+ li.append(tags);
+ r[1].append(li);
+ sidebarLinkMap[id] = [a, null];
+ }
+ }
+ });
+});
diff --git a/python/docs/_templates/layout.html b/python/docs/_templates/layout.html
new file mode 100644
index 0000000000..ab36ebabab
--- /dev/null
+++ b/python/docs/_templates/layout.html
@@ -0,0 +1,6 @@
+{% extends "!layout.html" %}
+{% set script_files = script_files + ["_static/pyspark.js"] %}
+{% set css_files = css_files + ['_static/pyspark.css'] %}
+{% block rootrellink %}
+ {{ super() }}
+{% endblock %}
diff --git a/python/docs/conf.py b/python/docs/conf.py
index 163987dd8e..365d6af514 100644
--- a/python/docs/conf.py
+++ b/python/docs/conf.py
@@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.2'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -135,7 +135,7 @@ html_logo = "../../docs/img/spark-logo-hd.png"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
--
GitLab