From ce6bddb5b3f8d3311d46d8fe994cf05f1fd66432 Mon Sep 17 00:00:00 2001
From: Beyang Liu <beyang@sourcegraph.com>
Date: Wed, 31 Aug 2016 12:20:05 -0700
Subject: [PATCH] add usage examples to Go docs

---
 lib/docs/filters/go/usages.rb             | 75 +++++++++++++++++++++++
 lib/docs/scrapers/go.rb                   |  2 +-
 test/lib/docs/filters/core/usages_test.rb | 58 ++++++++++++++++++
 3 files changed, 134 insertions(+), 1 deletion(-)
 create mode 100644 lib/docs/filters/go/usages.rb
 create mode 100644 test/lib/docs/filters/core/usages_test.rb

diff --git a/lib/docs/filters/go/usages.rb b/lib/docs/filters/go/usages.rb
new file mode 100644
index 00000000..92ae1e64
--- /dev/null
+++ b/lib/docs/filters/go/usages.rb
@@ -0,0 +1,75 @@
+module Docs
+  class Go
+    class UsagesFilter < Filter
+      def call
+        # Add examples link to every type and non-constructor function
+        css('h2').each do |node|
+          if node.text.start_with?('type ') or node.text.start_with?('func ')
+            name = node.attr("id")
+            node.add_next_sibling("<a href=\"#{usages_url(name)}\">Examples</a>")
+          end
+        end
+
+        # Add examples link to every method and constructor function
+        css('h3').each do |node|
+          if node.text.start_with?('func ')
+            name = node.attr("id").gsub(".", "/")
+            node.add_next_sibling("<a href=\"#{usages_url(name)}\">Examples</a>")
+          end
+        end
+
+        # Add examples link to every package variable
+        css('h2#pkg-variables').each do |var_header_node|
+          var_nodes = []
+          cur_node = var_header_node.next_element
+          while cur_node != nil
+            if cur_node.name == 'h2'
+              break
+            end
+            if cur_node.name == 'pre'
+              var_nodes.push(cur_node)
+            end
+            cur_node = cur_node.next_element
+          end
+          var_nodes.each do |node|
+            if node.name == "pre"
+              node.text.scan(/^\s*(?:var\s+)?([A-Za-z0-9_]+)\s+(?:[A-Za-z0-9_]+\s+)?=\s+/).each do |match|
+                name = match[0]
+                node.add_next_sibling("<div><a href=\"#{usages_url(name)}\">#{name} examples</a></div>")
+              end
+            end
+          end
+        end
+
+        # Add examples link to every package constant
+        css('h2#pkg-constants').each do |const_header_node|
+          const_nodes = []
+          cur_node = const_header_node.next_element
+          while cur_node != nil
+            if cur_node.name == 'h2'
+              break
+            end
+            if cur_node.name == 'pre'
+              const_nodes.push(cur_node)
+            end
+            cur_node = cur_node.next_element
+          end
+          const_nodes.each do |node|
+            if node.name == "pre"
+              node.text.scan(/^\s*(?:const\s+)?([A-Za-z0-9_]+)\s+(?:[A-Za-z0-9_]+\s+)?=\s+/).each do |match|
+                name = match[0]
+                node.add_next_sibling("<div><a href=\"#{usages_url(name)}\">#{name} examples</a></div>")
+              end
+            end
+          end
+        end
+
+        doc
+      end
+
+      def usages_url(name)
+        return "https://sourcegraph.com/github.com/golang/go/-/land/GoPackage/#{subpath}-/#{name}?utm_source=devdocs.io&utm_medium=web&utm_campaign=docs"
+      end
+    end
+  end
+end
diff --git a/lib/docs/scrapers/go.rb b/lib/docs/scrapers/go.rb
index 5060604d..114f8625 100644
--- a/lib/docs/scrapers/go.rb
+++ b/lib/docs/scrapers/go.rb
@@ -8,7 +8,7 @@ module Docs
       code: 'https://go.googlesource.com/go'
     }
 
-    html_filters.push 'go/clean_html', 'go/entries'
+    html_filters.push 'go/clean_html', 'go/entries', 'go/usages'
 
     options[:trailing_slash] = true
     options[:container] = '#page .container'
diff --git a/test/lib/docs/filters/core/usages_test.rb b/test/lib/docs/filters/core/usages_test.rb
new file mode 100644
index 00000000..ad4e747a
--- /dev/null
+++ b/test/lib/docs/filters/core/usages_test.rb
@@ -0,0 +1,58 @@
+require 'test_helper'
+require 'docs'
+
+class UsagesFilterTest < MiniTest::Spec
+  include FilterTestHelper
+  self.filter_class = Docs::Go::UsagesFilter
+
+  before do
+    context[:base_url] = 'http://example.com/path/'
+    context[:url] = 'http://example.com/path/bytes/'
+  end
+
+  it "adds examples link for functions" do
+    @body = '<div><h2 id="Contains">func Contains  </h2></div>'
+    assert_equal "<div>\n"\
+                 "<h2 id=\"Contains\">func Contains  </h2>\n"\
+                 "<a href=\"https://sourcegraph.com/github.com/golang/go/-/land/GoPackage/bytes/-/Contains?utm_source=devdocs.io&amp;utm_medium=web&amp;utm_campaign=docs\">Examples</a>\n"\
+                 "</div>", filter_output_string
+  end
+
+  it "adds examples link for methods" do
+    @body =
+      '<div><h3 id="Buffer.WriteString">func (*Buffer) <a href="https://golang.org/src/bytes/buffer.go?s=4916:4973#L131">WriteString</a>  </h3></div>'
+    assert_equal "<div>\n"\
+                 "<h3 id=\"Buffer.WriteString\">func (*Buffer) <a href=\"https://golang.org/src/bytes/buffer.go?s=4916:4973#L131\">WriteString</a>  </h3>\n"\
+                 "<a href=\"https://sourcegraph.com/github.com/golang/go/-/land/GoPackage/bytes/-/Buffer/WriteString?utm_source=devdocs.io&amp;utm_medium=web&amp;utm_campaign=docs\">Examples</a>\n"\
+                 "</div>", filter_output_string
+  end
+
+  it "adds examples link for variables" do
+    @body =
+      "<div>\n"\
+      "<h2 id=\"pkg-variables\">Variables</h2>\n"\
+      "<pre data-language=\"go\" class=\" language-go\"><span class=\"token keyword\">var</span> ErrTooLarge <span class=\"token operator\">=</span> errors<span class=\"token punctuation\">.</span><span class=\"token function\">New</span><span class=\"token punctuation\">(</span><span class=\"token string\">\"bytes.Buffer: too large\"</span><span class=\"token punctuation\">)</span></pre>\n"\
+      "</div>"
+
+    assert_equal "<div>\n"\
+                 "<h2 id=\"pkg-variables\">Variables</h2>\n"\
+                 "<pre data-language=\"go\" class=\" language-go\"><span class=\"token keyword\">var</span> ErrTooLarge <span class=\"token operator\">=</span> errors<span class=\"token punctuation\">.</span><span class=\"token function\">New</span><span class=\"token punctuation\">(</span><span class=\"token string\">\"bytes.Buffer: too large\"</span><span class=\"token punctuation\">)</span></pre>\n"\
+                 "<div><a href=\"https://sourcegraph.com/github.com/golang/go/-/land/GoPackage/bytes/-/ErrTooLarge?utm_source=devdocs.io&amp;utm_medium=web&amp;utm_campaign=docs\">ErrTooLarge examples</a></div>\n"\
+                 "</div>", filter_output_string
+  end
+
+  it "adds examples link for constants" do
+    @body =
+      "<div>\n"\
+      "<h2 id=\"pkg-constants\">Constants</h2>\n"\
+      "<pre data-language=\"go\" class=\" language-go\"><span class=\"token keyword\">const</span> Size <span class=\"token operator\">=</span> <span class=\"token number\">4</span></pre>\n"\
+      "</div>"
+
+    assert_equal "<div>\n"\
+                 "<h2 id=\"pkg-constants\">Constants</h2>\n"\
+                 "<pre data-language=\"go\" class=\" language-go\"><span class=\"token keyword\">const</span> Size <span class=\"token operator\">=</span> <span class=\"token number\">4</span></pre>\n"\
+                 "<div><a href=\"https://sourcegraph.com/github.com/golang/go/-/land/GoPackage/bytes/-/Size?utm_source=devdocs.io&amp;utm_medium=web&amp;utm_campaign=docs\">Size examples</a></div>\n"\
+                 "</div>", filter_output_string
+  end
+
+end