From 5d9789e46b73994db8de1089dd0de735456abf3b Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 22 Apr 2017 12:44:22 -0700 Subject: [PATCH 01/11] Include "Help make this better" text on track topic pages Issue #3355 pointed out that the instructions for filing an issue or submitting a patch were not showing up on language track topic pages. This adds that text to the bottom of those pages. --- app/presenters/track.rb | 24 ++++++++++++++++-------- test/app/presenters/track_test.rb | 18 ++++++++++++++++-- 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index c8612b743c..95efab15d1 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -17,12 +17,12 @@ def method_missing(method, *args) def docs track_docs = trackler_track.docs(image_path: "/api/v1/tracks/%s/images/docs/img" % @track_id) - track_docs.each_pair do |topic_name, topic_content| - track_docs[topic_name] = if topic_content.present? - topic_content - else - fallback_topic_content(topic_name) - end + track_docs.each_pair do |topic_key, topic_content| + track_docs[topic_key] = if topic_content.present? + [topic_content.strip, better_content(topic_key)].join("\n") + else + fallback_topic_content(topic_key) + end end track_docs @@ -30,8 +30,8 @@ def docs private - def fallback_topic_content(topic_name) - filepath = "./x/docs/md/track/#{topic_name.upcase}.md" + def fallback_topic_content(topic_key) + filepath = "./x/docs/md/track/#{topic_key.upcase}.md" return '' unless File.exist?(filepath) File.read(filepath) end @@ -40,6 +40,14 @@ def trackler_track Trackler.tracks[@track_id] end + def better_content(topic_key) + File. + read("./x/docs/md/track/BETTER.md"). + gsub('REPO', trackler_track.repository). + gsub('TOPIC', topic_key.to_s.upcase). + gsub('EXT', trackler_track.doc_format) + end + end end end diff --git a/test/app/presenters/track_test.rb b/test/app/presenters/track_test.rb index 2800496b97..e865e47339 100644 --- a/test/app/presenters/track_test.rb +++ b/test/app/presenters/track_test.rb @@ -7,20 +7,34 @@ class PresentersTrackTest < Minitest::Test def setup @track = ExercismWeb::Presenters::Track.new("test_track") @trackler_track = Object.new + @track.stubs(:trackler_track).returns(@trackler_track) @track.stubs(:fallback_topic_content).returns("Default topic content") + + @trackler_track.stubs(:repository).returns("https://github.com/exercism/test_track") + @trackler_track.stubs(:doc_format).returns("md") end def test_docs_with_trackler_content trackler_docs = OpenStruct.new(test_topic: "Track-specific content from Trackler") @trackler_track.stubs(:docs).returns(trackler_docs) - assert_equal @track.docs["test_topic"], "Track-specific content from Trackler" + topic_doc = @track.docs["test_topic"] + + assert topic_doc.include?("Track-specific content from Trackler") + assert topic_doc.include?("Help us explain this better!") + assert topic_doc.include?("File a GitHub issue at https://github.com/exercism/test_track") + assert topic_doc.include?("https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md") end def test_docs_without_trackler_content trackler_docs = OpenStruct.new(test_topic: "") @trackler_track.stubs(:docs).returns(trackler_docs) - assert_equal @track.docs["test_topic"], "Default topic content" + topic_doc = @track.docs["test_topic"] + + assert topic_doc.include? "Default topic content" + assert !topic_doc.include?("Help us explain this better!") + assert !topic_doc.include?("File a GitHub issue at https://github.com/exercism/test_track") + assert !topic_doc.include?("https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md") end def test_method_delegated_to_trackler_track From c1ebad95bc5694968d9a00ab45db8c2947bf9558 Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 22 Apr 2017 12:55:08 -0700 Subject: [PATCH 02/11] Remove unuses X::Docs::Track class We're no longer using X::Docs::Track to display track-specific documentation. Instead, we have a Track presenter that wraps data returned by the Trackler gem. --- x/docs.rb | 2 +- x/docs/track.rb | 41 ----------------------------------------- 2 files changed, 1 insertion(+), 42 deletions(-) delete mode 100644 x/docs/track.rb diff --git a/x/docs.rb b/x/docs.rb index 634e7d76f0..548c6ca994 100644 --- a/x/docs.rb +++ b/x/docs.rb @@ -1,3 +1,3 @@ -%w(help intro track cli launch).each do |klass| +%w(help intro cli launch).each do |klass| require_relative "docs/#{klass}" end diff --git a/x/docs/track.rb b/x/docs/track.rb deleted file mode 100644 index 6b0f6264bd..0000000000 --- a/x/docs/track.rb +++ /dev/null @@ -1,41 +0,0 @@ -module X - module Docs - # Enhances the track-specific documentation, adding - # defaults where missing and embellishments that encourage - # people to submit improvements. - class Track - TOPICS = [:about, :tests, :installation, :learning, :resources].freeze - - attr_reader(*TOPICS) - def initialize(data, repository, doc_ext) - @data = data - @repository = repository - @doc_ext = doc_ext - - TOPICS.each do |topic| - instance_variable_set(:"@#{topic}", value(topic.to_s)) - end - end - - private - - attr_reader :repository, :data, :doc_ext - - def value(topic) - if data[topic].empty? - read(topic).gsub('REPO', repository) - else - [data[topic].strip, better(topic)].join("\n") - end - end - - def better(topic) - read('better').gsub('REPO', repository).gsub('TOPIC', topic.upcase).gsub('EXT', doc_ext) - end - - def read(topic) - File.read("./x/docs/md/track/#{topic.upcase}.md") - end - end - end -end From dea1dc190e5aac4cf2089b06a12a7c6e3bfb5f15 Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 22 Apr 2017 13:46:33 -0700 Subject: [PATCH 03/11] Use "refute" instead of "assert !" --- test/app/presenters/track_test.rb | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/test/app/presenters/track_test.rb b/test/app/presenters/track_test.rb index e865e47339..8e12da2652 100644 --- a/test/app/presenters/track_test.rb +++ b/test/app/presenters/track_test.rb @@ -20,10 +20,10 @@ def test_docs_with_trackler_content @trackler_track.stubs(:docs).returns(trackler_docs) topic_doc = @track.docs["test_topic"] - assert topic_doc.include?("Track-specific content from Trackler") - assert topic_doc.include?("Help us explain this better!") - assert topic_doc.include?("File a GitHub issue at https://github.com/exercism/test_track") - assert topic_doc.include?("https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md") + assert topic_doc.include? "Track-specific content from Trackler" + assert topic_doc.include? "Help us explain this better!" + assert topic_doc.include? "File a GitHub issue at https://github.com/exercism/test_track" + assert topic_doc.include? "https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md" end def test_docs_without_trackler_content @@ -32,9 +32,9 @@ def test_docs_without_trackler_content topic_doc = @track.docs["test_topic"] assert topic_doc.include? "Default topic content" - assert !topic_doc.include?("Help us explain this better!") - assert !topic_doc.include?("File a GitHub issue at https://github.com/exercism/test_track") - assert !topic_doc.include?("https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md") + refute topic_doc.include? "Help us explain this better!" + refute topic_doc.include? "File a GitHub issue at https://github.com/exercism/test_track" + refute topic_doc.include? "https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md" end def test_method_delegated_to_trackler_track From 9b714d6b28ea00b6d09bc17d0d1442de178d194a Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 22 Apr 2017 16:28:22 -0700 Subject: [PATCH 04/11] Clarify method name --- app/presenters/track.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index 95efab15d1..f2b72ec554 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -19,7 +19,7 @@ def docs track_docs.each_pair do |topic_key, topic_content| track_docs[topic_key] = if topic_content.present? - [topic_content.strip, better_content(topic_key)].join("\n") + [topic_content.strip, contributing_instructions(topic_key)].join("\n") else fallback_topic_content(topic_key) end @@ -40,7 +40,7 @@ def trackler_track Trackler.tracks[@track_id] end - def better_content(topic_key) + def contributing_instructions(topic_key) File. read("./x/docs/md/track/BETTER.md"). gsub('REPO', trackler_track.repository). From 1a44a1e9248458d1ef1803e93a7a2fa112ad9fd1 Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 22 Apr 2017 16:59:20 -0700 Subject: [PATCH 05/11] Refactor Presenters::Track#docs --- app/presenters/track.rb | 44 ++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index f2b72ec554..cd6cdf8c2d 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -15,31 +15,37 @@ def method_missing(method, *args) end def docs - track_docs = trackler_track.docs(image_path: "/api/v1/tracks/%s/images/docs/img" % @track_id) - - track_docs.each_pair do |topic_key, topic_content| - track_docs[topic_key] = if topic_content.present? - [topic_content.strip, contributing_instructions(topic_key)].join("\n") - else - fallback_topic_content(topic_key) - end + trackler_topics.each_with_object(OpenStruct.new) do |topic_key, result| + result[topic_key] = topic_content(topic_key) end - - track_docs end private - def fallback_topic_content(topic_key) - filepath = "./x/docs/md/track/#{topic_key.upcase}.md" - return '' unless File.exist?(filepath) - File.read(filepath) - end - def trackler_track Trackler.tracks[@track_id] end + def trackler_docs + trackler_track.docs(image_path: "/api/v1/tracks/%s/images/docs/img" % @track_id) + end + + def trackler_topics + trackler_docs.to_h.keys + end + + def trackler_topic_content(topic_key) + trackler_docs[topic_key] + end + + def topic_content(topic_key) + if trackler_topic_content(topic_key).present? + [trackler_topic_content(topic_key).strip, contributing_instructions(topic_key)].join("\n") + else + fallback_topic_content(topic_key) + end + end + def contributing_instructions(topic_key) File. read("./x/docs/md/track/BETTER.md"). @@ -48,6 +54,12 @@ def contributing_instructions(topic_key) gsub('EXT', trackler_track.doc_format) end + def fallback_topic_content(topic_key) + filepath = "./x/docs/md/track/#{topic_key.upcase}.md" + return '' unless File.exist?(filepath) + File.read(filepath) + end + end end end From 827a210d380561a2f2f6913f50081cea27a5fce5 Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 22 Apr 2017 17:25:29 -0700 Subject: [PATCH 06/11] Don't stub out the object under test --- test/app/presenters/track_test.rb | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/test/app/presenters/track_test.rb b/test/app/presenters/track_test.rb index 8e12da2652..a45f5178d4 100644 --- a/test/app/presenters/track_test.rb +++ b/test/app/presenters/track_test.rb @@ -6,32 +6,31 @@ class PresentersTrackTest < Minitest::Test def setup @track = ExercismWeb::Presenters::Track.new("test_track") - @trackler_track = Object.new - @track.stubs(:trackler_track).returns(@trackler_track) - @track.stubs(:fallback_topic_content).returns("Default topic content") + trackler_tracks = Object.new + @trackler_track = Object.new + Trackler.stubs(:tracks).returns(trackler_tracks) + trackler_tracks.stubs(:[]).returns(@trackler_track) @trackler_track.stubs(:repository).returns("https://github.com/exercism/test_track") @trackler_track.stubs(:doc_format).returns("md") end def test_docs_with_trackler_content - trackler_docs = OpenStruct.new(test_topic: "Track-specific content from Trackler") - @trackler_track.stubs(:docs).returns(trackler_docs) - topic_doc = @track.docs["test_topic"] + @trackler_track.stubs(:docs).returns(OpenStruct.new(about: "Track-specific content from Trackler")) + topic_doc = @track.docs["about"] assert topic_doc.include? "Track-specific content from Trackler" assert topic_doc.include? "Help us explain this better!" assert topic_doc.include? "File a GitHub issue at https://github.com/exercism/test_track" - assert topic_doc.include? "https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md" + assert topic_doc.include? "https://github.com/exercism/test_track/blob/master/docs/ABOUT.md" end def test_docs_without_trackler_content - trackler_docs = OpenStruct.new(test_topic: "") - @trackler_track.stubs(:docs).returns(trackler_docs) - topic_doc = @track.docs["test_topic"] + @trackler_track.stubs(:docs).returns(OpenStruct.new(about: "")) + topic_doc = @track.docs["about"] - assert topic_doc.include? "Default topic content" + assert topic_doc.include? "We're missing a short introduction about the language." refute topic_doc.include? "Help us explain this better!" refute topic_doc.include? "File a GitHub issue at https://github.com/exercism/test_track" refute topic_doc.include? "https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md" From 3afedaaebdce4d7d4637234b09a8bf8b9ad89dcc Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sun, 23 Apr 2017 07:57:12 -0700 Subject: [PATCH 07/11] Clean up Presenters::Track tests --- test/app/presenters/track_test.rb | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/test/app/presenters/track_test.rb b/test/app/presenters/track_test.rb index a45f5178d4..164c46f622 100644 --- a/test/app/presenters/track_test.rb +++ b/test/app/presenters/track_test.rb @@ -5,20 +5,19 @@ class PresentersTrackTest < Minitest::Test def setup - @track = ExercismWeb::Presenters::Track.new("test_track") + @trackler_track = Object.new + @trackler_track.stubs(:repository).returns("https://github.com/exercism/test_track") + @trackler_track.stubs(:doc_format).returns("md") trackler_tracks = Object.new - @trackler_track = Object.new + trackler_tracks.stubs(:[]).returns(@trackler_track) Trackler.stubs(:tracks).returns(trackler_tracks) - trackler_tracks.stubs(:[]).returns(@trackler_track) - @trackler_track.stubs(:repository).returns("https://github.com/exercism/test_track") - @trackler_track.stubs(:doc_format).returns("md") end def test_docs_with_trackler_content @trackler_track.stubs(:docs).returns(OpenStruct.new(about: "Track-specific content from Trackler")) - topic_doc = @track.docs["about"] + topic_doc = ExercismWeb::Presenters::Track.new("test_track").docs["about"] assert topic_doc.include? "Track-specific content from Trackler" assert topic_doc.include? "Help us explain this better!" @@ -28,16 +27,13 @@ def test_docs_with_trackler_content def test_docs_without_trackler_content @trackler_track.stubs(:docs).returns(OpenStruct.new(about: "")) - topic_doc = @track.docs["about"] + topic_doc = ExercismWeb::Presenters::Track.new("test_track").docs["about"] assert topic_doc.include? "We're missing a short introduction about the language." - refute topic_doc.include? "Help us explain this better!" - refute topic_doc.include? "File a GitHub issue at https://github.com/exercism/test_track" - refute topic_doc.include? "https://github.com/exercism/test_track/blob/master/docs/TEST_TOPIC.md" end def test_method_delegated_to_trackler_track @trackler_track.stubs(:exists?).returns(true) - assert_equal @track.exists?, true + assert_equal ExercismWeb::Presenters::Track.new("test_track").exists?, true end end From d690e725a79ffb04829229d18e9bbf9d2e0fb83e Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Fri, 28 Apr 2017 07:42:11 -0700 Subject: [PATCH 08/11] Fix broken link on fallback content page Addresses https://github.com/exercism/exercism.io/issues/3490 --- app/presenters/track.rb | 12 ++++++------ test/app/presenters/track_test.rb | 1 + 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index cd6cdf8c2d..93cd36d9f0 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -47,17 +47,17 @@ def topic_content(topic_key) end def contributing_instructions(topic_key) - File. - read("./x/docs/md/track/BETTER.md"). - gsub('REPO', trackler_track.repository). - gsub('TOPIC', topic_key.to_s.upcase). - gsub('EXT', trackler_track.doc_format) + content_with_trackler_data("./x/docs/md/track/BETTER.md").gsub('TOPIC', topic_key.to_s.upcase) end def fallback_topic_content(topic_key) filepath = "./x/docs/md/track/#{topic_key.upcase}.md" return '' unless File.exist?(filepath) - File.read(filepath) + content_with_trackler_data(filepath) + end + + def content_with_trackler_data(filepath) + File.read(filepath).gsub('REPO', trackler_track.repository).gsub('EXT', trackler_track.doc_format) end end diff --git a/test/app/presenters/track_test.rb b/test/app/presenters/track_test.rb index 164c46f622..e72d255ade 100644 --- a/test/app/presenters/track_test.rb +++ b/test/app/presenters/track_test.rb @@ -30,6 +30,7 @@ def test_docs_without_trackler_content topic_doc = ExercismWeb::Presenters::Track.new("test_track").docs["about"] assert topic_doc.include? "We're missing a short introduction about the language." + assert topic_doc.include? "https://github.com/exercism/test_track" end def test_method_delegated_to_trackler_track From 33cdb6812164e186d88287c83359fa81bb032204 Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Fri, 28 Apr 2017 22:20:06 -0700 Subject: [PATCH 09/11] Check for template existance and read template in same method --- app/presenters/track.rb | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index 93cd36d9f0..ee401deff6 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -47,17 +47,17 @@ def topic_content(topic_key) end def contributing_instructions(topic_key) - content_with_trackler_data("./x/docs/md/track/BETTER.md").gsub('TOPIC', topic_key.to_s.upcase) + populate_template_with_trackler_data(File.read("./x/docs/md/track/BETTER.md")).gsub('TOPIC', topic_key.to_s.upcase) end def fallback_topic_content(topic_key) filepath = "./x/docs/md/track/#{topic_key.upcase}.md" return '' unless File.exist?(filepath) - content_with_trackler_data(filepath) + populate_template_with_trackler_data(File.read(filepath)) end - def content_with_trackler_data(filepath) - File.read(filepath).gsub('REPO', trackler_track.repository).gsub('EXT', trackler_track.doc_format) + def populate_template_with_trackler_data(template) + template.gsub('REPO', trackler_track.repository).gsub('EXT', trackler_track.doc_format) end end From 2b344986e63e780cffe60f6a73e52a04ed0b91ad Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Fri, 28 Apr 2017 22:26:44 -0700 Subject: [PATCH 10/11] Explicitly name file outputs for clarity --- app/presenters/track.rb | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index ee401deff6..084b899a1c 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -47,13 +47,15 @@ def topic_content(topic_key) end def contributing_instructions(topic_key) - populate_template_with_trackler_data(File.read("./x/docs/md/track/BETTER.md")).gsub('TOPIC', topic_key.to_s.upcase) + template = File.read("./x/docs/md/track/BETTER.md") + populate_template_with_trackler_data(template).gsub('TOPIC', topic_key.to_s.upcase) end def fallback_topic_content(topic_key) - filepath = "./x/docs/md/track/#{topic_key.upcase}.md" - return '' unless File.exist?(filepath) - populate_template_with_trackler_data(File.read(filepath)) + template_filepath = "./x/docs/md/track/#{topic_key.upcase}.md" + return '' unless File.exist?(template_filepath) + template = File.read(template_filepath) + populate_template_with_trackler_data(template) end def populate_template_with_trackler_data(template) From 483e17f870acca16b3cf0f4a25bf080c3eb72ad2 Mon Sep 17 00:00:00 2001 From: Nick Holden Date: Sat, 29 Apr 2017 10:45:43 -0700 Subject: [PATCH 11/11] Define location and file format for shared track topic templates in single method --- app/presenters/track.rb | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/app/presenters/track.rb b/app/presenters/track.rb index 084b899a1c..4bd9f22c5b 100644 --- a/app/presenters/track.rb +++ b/app/presenters/track.rb @@ -47,12 +47,12 @@ def topic_content(topic_key) end def contributing_instructions(topic_key) - template = File.read("./x/docs/md/track/BETTER.md") + template = File.read(shared_template_filepath("BETTER")) populate_template_with_trackler_data(template).gsub('TOPIC', topic_key.to_s.upcase) end def fallback_topic_content(topic_key) - template_filepath = "./x/docs/md/track/#{topic_key.upcase}.md" + template_filepath = shared_template_filepath(topic_key.upcase) return '' unless File.exist?(template_filepath) template = File.read(template_filepath) populate_template_with_trackler_data(template) @@ -62,6 +62,10 @@ def populate_template_with_trackler_data(template) template.gsub('REPO', trackler_track.repository).gsub('EXT', trackler_track.doc_format) end + def shared_template_filepath(template_name) + "./x/docs/md/track/#{template_name}.md" + end + end end end