FEATURE: Optionally show topic excerpts in docs index

This commit adds a new docs_show_topic_excerpts site setting
which, when enabled and used in conjunction either with the
always_include_topic_excerpts site setting or the
serialize_topic_excerpts theme modifier.

For the theme modifier, this commit also fixes an issue
with the Docs::Query class. Since we were re-initializing
Guardian within the class (rather than using the guardian
passed down from the controller), we did not have the request
information needed to determine theme_id, which meant that
the theme modifier had no effect. We now pass down guardian
from the controller instead. In general guardian is almost
always better than a user object, since we can always just
call guardian.user.

Adds a simple system spec as well.

app/controllers/docs/docs_controller.rb

@@ -18,7 +18,7 @@ module Docs
         page: params[:page],
       }
 
-      query = Docs::Query.new(current_user, filters).list
+      query = Docs::Query.new(guardian, filters).list
 
       if filters[:topic].present?
         begin

assets/javascripts/discourse/components/docs-topic-list.js

@@ -17,6 +17,10 @@ export default Component.extend({
     return order === "activity";
   },
 
+  showExcerpt() {
+    return this.siteSettings.docs_show_topic_excerpts;
+  },
+
   @action
   sortListActivity() {
     this.sortBy("activity");

assets/javascripts/discourse/templates/components/docs-topic-list.hbs

@@ -28,7 +28,12 @@
 
     <tbody class="topic-list-body">
       {{#each topics as |topic|}}
-        {{raw "docs-topic-list-item" topic=topic urlPath=urlPath}}
+        {{raw
+          "docs-topic-list-item"
+          topic=topic
+          urlPath=urlPath
+          showExcerpt=showExcerpt
+        }}
       {{/each}}
     </tbody>
   </table>

assets/javascripts/discourse/templates/docs-topic-list-item.hbr

@@ -8,6 +8,10 @@
       {{category-link topic.category}}
       {{discourse-tags topic mode="list"}}
     </span>
+
+    {{#if showExcerpt}}
+      {{raw "list/topic-excerpt" topic=topic}}
+    {{/if}}
   </td>
   <td class="topic-list-data">
     {{format-date topic.bumped_at format="tiny" noTitle="true"}}

config/settings.yml

@@ -19,3 +19,6 @@ plugins:
   docs_add_search_menu_tip:
     default: true
     client: true
+  docs_show_topic_excerpts:
+    default: false
+    client: true

lib/docs/query.rb

@@ -2,8 +2,8 @@
 
 module Docs
   class Query
-    def initialize(user = nil, filters = {})
-      @user = user
+    def initialize(guardian, filters = {})
+      @guardian = guardian
       @filters = filters
       @limit = 30
     end
@@ -19,7 +19,7 @@ module Docs
     def list
       # query for topics matching selected categories & tags
       opts = { no_definitions: true, limit: false }
-      tq = TopicQuery.new(@user, opts)
+      tq = TopicQuery.new(@guardian.user, opts)
       results = tq.list_docs_topics
       results = results.left_outer_joins(:tags)
       results = results.references(:categories)
@@ -137,7 +137,7 @@ module Docs
       # assemble the object
       topic_query = tq.create_list(:docs, { unordered: true }, results)
 
-      topic_list = TopicListSerializer.new(topic_query, scope: Guardian.new(@user)).as_json
+      topic_list = TopicListSerializer.new(topic_query, scope: @guardian).as_json
 
       if end_of_list.nil?
         topic_list["load_more_url"] = load_more_url
@@ -156,7 +156,7 @@ module Docs
         tags_object << { id: tag[0], count: tag[1], active: active || false }
       end
 
-      allowed_tags = DiscourseTagging.filter_allowed_tags(Guardian.new(@user)).map(&:name)
+      allowed_tags = DiscourseTagging.filter_allowed_tags(@guardian).map(&:name)
 
       tags_object = tags_object.select { |tag| allowed_tags.include?(tag[:id]) }
 

spec/system/docs_index_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+describe "Discourse Docs | Index", type: :system do
+  fab!(:current_user) { Fabricate(:user) }
+  fab!(:category) { Fabricate(:category) }
+  fab!(:topic_1) { Fabricate(:topic, category: category) }
+  fab!(:topic_2) { Fabricate(:topic, category: category) }
+  fab!(:post_1) { Fabricate(:post, topic: topic_1) }
+  fab!(:post_2) { Fabricate(:post, topic: topic_2) }
+
+  before do
+    SiteSetting.docs_enabled = true
+    SiteSetting.docs_categories = category.id.to_s
+    sign_in(current_user)
+  end
+
+  it "does not error when showing the index" do
+    visit("/docs")
+    expect(page).to have_css(".docs-topic-link", text: topic_1.title)
+    expect(page).to have_css(".docs-topic-link", text: topic_2.title)
+  end
+
+  describe "topic excerpts" do
+    before do
+      topic_1.update_excerpt(post_1.excerpt_for_topic)
+      topic_2.update_excerpt(post_2.excerpt_for_topic)
+    end
+
+    it "does not show the topic excerpts by default" do
+      visit("/docs")
+      expect(page).to have_no_css(".topic-excerpt")
+    end
+
+    context "when docs_show_topic_excerpts is true" do
+      before do
+        SiteSetting.docs_show_topic_excerpts = true
+        SiteSetting.always_include_topic_excerpts = true
+      end
+
+      it "shows the excerpts" do
+        visit("/docs")
+        expect(page).to have_css(".topic-excerpt", text: topic_1.excerpt)
+        expect(page).to have_css(".topic-excerpt", text: topic_2.excerpt)
+      end
+    end
+  end
+end