Skip to content

Commit ce6bddb

Browse files
beyangbeyang
committed
add usage examples to Go docs
1 parent 5db1ca7 commit ce6bddb

3 files changed

Lines changed: 134 additions & 1 deletion

File tree

‎lib/docs/filters/go/usages.rb‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
module Docs
2+
class Go
3+
class UsagesFilter < Filter
4+
def call
5+
# Add examples link to every type and non-constructor function
6+
css('h2').each do |node|
7+
if node.text.start_with?('type ') or node.text.start_with?('func ')
8+
name = node.attr("id")
9+
node.add_next_sibling("<a href=\"#{usages_url(name)}\">Examples</a>")
10+
end
11+
end
12+
13+
# Add examples link to every method and constructor function
14+
css('h3').each do |node|
15+
if node.text.start_with?('func ')
16+
name = node.attr("id").gsub(".", "/")
17+
node.add_next_sibling("<a href=\"#{usages_url(name)}\">Examples</a>")
18+
end
19+
end
20+
21+
# Add examples link to every package variable
22+
css('h2#pkg-variables').each do |var_header_node|
23+
var_nodes = []
24+
cur_node = var_header_node.next_element
25+
while cur_node != nil
26+
if cur_node.name == 'h2'
27+
break
28+
end
29+
if cur_node.name == 'pre'
30+
var_nodes.push(cur_node)
31+
end
32+
cur_node = cur_node.next_element
33+
end
34+
var_nodes.each do |node|
35+
if node.name == "pre"
36+
node.text.scan(/^\s*(?:var\s+)?([A-Za-z0-9_]+)\s+(?:[A-Za-z0-9_]+\s+)?=\s+/).each do |match|
37+
name = match[0]
38+
node.add_next_sibling("<div><a href=\"#{usages_url(name)}\">#{name} examples</a></div>")
39+
end
40+
end
41+
end
42+
end
43+
44+
# Add examples link to every package constant
45+
css('h2#pkg-constants').each do |const_header_node|
46+
const_nodes = []
47+
cur_node = const_header_node.next_element
48+
while cur_node != nil
49+
if cur_node.name == 'h2'
50+
break
51+
end
52+
if cur_node.name == 'pre'
53+
const_nodes.push(cur_node)
54+
end
55+
cur_node = cur_node.next_element
56+
end
57+
const_nodes.each do |node|
58+
if node.name == "pre"
59+
node.text.scan(/^\s*(?:const\s+)?([A-Za-z0-9_]+)\s+(?:[A-Za-z0-9_]+\s+)?=\s+/).each do |match|
60+
name = match[0]
61+
node.add_next_sibling("<div><a href=\"#{usages_url(name)}\">#{name} examples</a></div>")
62+
end
63+
end
64+
end
65+
end
66+
67+
doc
68+
end
69+
70+
def usages_url(name)
71+
return "https://sourcegraph.com/github.com/golang/go/-/land/GoPackage/#{subpath}-/#{name}?utm_source=devdocs.io&utm_medium=web&utm_campaign=docs"
72+
end
73+
end
74+
end
75+
end

‎lib/docs/scrapers/go.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ class Go < UrlScraper
88
code: 'https://go.googlesource.com/go'
99
}
1010

11-
html_filters.push 'go/clean_html', 'go/entries'
11+
html_filters.push 'go/clean_html', 'go/entries', 'go/usages'
1212

1313
options[:trailing_slash] = true
1414
options[:container] = '#page .container'

‎test/lib/docs/filters/core/usages_test.rb‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
require 'test_helper'
2+
require 'docs'
3+
4+
class UsagesFilterTest < MiniTest::Spec
5+
include FilterTestHelper
6+
self.filter_class = Docs::Go::UsagesFilter
7+
8+
before do
9+
context[:base_url] = 'http://example.com/path/'
10+
context[:url] = 'http://example.com/path/bytes/'
11+
end
12+
13+
it "adds examples link for functions" do
14+
@body = '<div><h2 id="Contains">func Contains </h2></div>'
15+
assert_equal "<div>\n"\
16+
"<h2 id=\"Contains\">func Contains </h2>\n"\
17+
"<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"\
18+
"</div>", filter_output_string
19+
end
20+
21+
it "adds examples link for methods" do
22+
@body =
23+
'<div><h3 id="Buffer.WriteString">func (*Buffer) <a href="https://golang.org/src/bytes/buffer.go?s=4916:4973#L131">WriteString</a> </h3></div>'
24+
assert_equal "<div>\n"\
25+
"<h3 id=\"Buffer.WriteString\">func (*Buffer) <a href=\"https://golang.org/src/bytes/buffer.go?s=4916:4973#L131\">WriteString</a> </h3>\n"\
26+
"<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"\
27+
"</div>", filter_output_string
28+
end
29+
30+
it "adds examples link for variables" do
31+
@body =
32+
"<div>\n"\
33+
"<h2 id=\"pkg-variables\">Variables</h2>\n"\
34+
"<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"\
35+
"</div>"
36+
37+
assert_equal "<div>\n"\
38+
"<h2 id=\"pkg-variables\">Variables</h2>\n"\
39+
"<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"\
40+
"<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"\
41+
"</div>", filter_output_string
42+
end
43+
44+
it "adds examples link for constants" do
45+
@body =
46+
"<div>\n"\
47+
"<h2 id=\"pkg-constants\">Constants</h2>\n"\
48+
"<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"\
49+
"</div>"
50+
51+
assert_equal "<div>\n"\
52+
"<h2 id=\"pkg-constants\">Constants</h2>\n"\
53+
"<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"\
54+
"<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"\
55+
"</div>", filter_output_string
56+
end
57+
58+
end

0 commit comments

Comments
 (0)