Display docs by position in config (#6986)

* Add position column to docs table

* Add sorted scope to document

* Store position for docs

* Order docs

* Show docs by position

* Use default value

app/commands/git/sync_doc.rb

@@ -1,7 +1,7 @@
 class Git::SyncDoc
   include Mandate
 
-  initialize_with :config, :section, :git_sha, track: nil
+  initialize_with :config, :section, :position, :git_sha, track: nil
 
   def call
     doc = Document.where(track:).create_or_find_by!(
@@ -26,7 +26,8 @@ def attributes
       git_path: config[:path],
       section:,
       title: config[:title],
-      blurb: config[:blurb]
+      blurb: config[:blurb],
+      position:
     }
   end
 end

app/commands/git/sync_main_docs.rb

@@ -17,8 +17,8 @@ def call
   def sync_config!(section)
     config = repo.section_config(section)
 
-    config.to_a.each do |doc_config|
-      Git::SyncDoc.(doc_config, section, repo.head_sha)
+    config.to_a.each_with_index do |doc_config, position|
+      Git::SyncDoc.(doc_config, section, position, repo.head_sha)
     end
   end
 

app/commands/git/sync_track_docs.rb

@@ -11,8 +11,8 @@ def call
 
     config = git_repo.read_json_blob(git_repo.head_commit, "docs/config.json")
 
-    config[:docs].to_a.each do |doc_config|
-      Git::SyncDoc.(doc_config, :tracks, git_repo.head_commit.oid, track:)
+    config[:docs].to_a.each_with_index do |doc_config, position|
+      Git::SyncDoc.(doc_config, :tracks, position, git_repo.head_commit.oid, track:)
     end
   end
 

app/helpers/view_components/docs_side_nav.rb

@@ -5,7 +5,7 @@ class DocsSideNav < ViewComponent
     def initialize(docs, selected_doc, track: nil)
       super()
 
-      @docs = docs.includes(:track)
+      @docs = docs.includes(:track).sorted
       @selected_doc = selected_doc
       @track = track
     end
@@ -100,7 +100,7 @@ def structured_docs
         levels << current
       end
 
-      paths = docs.map(&:slug).sort
+      paths = docs.map(&:slug)
       paths.each_with_object({}) do |path, tree|
         # Only get docs that are:
         # - top level
@@ -123,7 +123,7 @@ def structured_docs
 
     memoize
     def slugs_with_children
-      paths = docs.map(&:slug).sort
+      paths = docs.map(&:slug)
       paths.select do |path|
         paths.any? { |otherpath| otherpath != path && otherpath.start_with?("#{path}/") }
       end

app/models/document.rb

@@ -10,6 +10,8 @@ class Document < ApplicationRecord
 
   belongs_to :track, optional: true
 
+  scope :sorted, -> { order(:position) }
+
   after_save_commit do
     Document::SyncToSearchIndex.defer(self)
   end

db/migrate/20240710082636_add_position_to_docs.rb

@@ -0,0 +1,9 @@
+class AddPositionToDocs < ActiveRecord::Migration[7.0]
+  def change
+    return if Rails.env.production?
+
+    add_column :documents, :position, :integer, null: false, limit: 1, default: 0
+    add_index :documents, [:track_id, :position]
+    add_index :documents, [:section, :position]
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.0].define(version: 2024_02_01_170724) do
+ActiveRecord::Schema[7.0].define(version: 2024_07_10_082636) do
   create_table "active_storage_attachments", charset: "utf8mb4", collation: "utf8mb4_unicode_ci", force: :cascade do |t|
     t.string "name", null: false
     t.string "record_type", null: false
@@ -152,7 +152,10 @@
     t.string "blurb"
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
+    t.integer "position", limit: 1, default: 0, null: false
+    t.index ["section", "position"], name: "index_documents_on_section_and_position"
     t.index ["slug"], name: "index_documents_on_slug"
+    t.index ["track_id", "position"], name: "index_documents_on_track_id_and_position"
     t.index ["track_id"], name: "index_documents_on_track_id"
     t.index ["uuid"], name: "index_documents_on_uuid", unique: true
   end

test/commands/git/sync_main_docs_test.rb

@@ -6,15 +6,27 @@ class Git::SyncMainDocsTest < ActiveSupport::TestCase
 
     Git::SyncMainDocs.()
 
-    assert_equal 1, Document.count
-    doc = Document.first
-    assert_nil doc.track
-    assert_equal '7c7139b9-a228-4691-a4e4-a0c39a6dd615', doc.uuid
-    assert_equal "building", doc.section
-    assert_equal "APEX", doc.slug
-    assert_equal "contributing/README.md", doc.git_path
-    assert_equal "Contributing to Exercism", doc.title
-    assert_equal "An overview of how to contribute to Exercism", doc.blurb
+    assert_equal 2, Document.count
+
+    doc_1 = Document.first
+    assert_nil doc_1.track
+    assert_equal '7c7139b9-a228-4691-a4e4-a0c39a6dd615', doc_1.uuid
+    assert_equal "building", doc_1.section
+    assert_equal "APEX", doc_1.slug
+    assert_equal "contributing/README.md", doc_1.git_path
+    assert_equal "Contributing to Exercism", doc_1.title
+    assert_equal "An overview of how to contribute to Exercism", doc_1.blurb
+    assert_equal 0, doc_1.position
+
+    doc_2 = Document.second
+    assert_nil doc_2.track
+    assert_equal 'd372e903-31fa-4918-a506-e3f939452828', doc_2.uuid
+    assert_equal "building", doc_2.section
+    assert_equal "configlet", doc_2.slug
+    assert_equal "building/configlet/README.md", doc_2.git_path
+    assert_equal "Configlet", doc_2.title
+    assert_equal "The canonical specifications for everything on Exercism", doc_2.blurb
+    assert_equal 1, doc_2.position
   end
 
   test "updates existing docs" do
@@ -24,18 +36,20 @@ class Git::SyncMainDocsTest < ActiveSupport::TestCase
       slug: "rlly",
       git_path: "incorrect/old.md",
       title: "Very wrong",
-      blurb: "Wrong"
+      blurb: "Wrong",
+      position: 3
 
     Git::SyncMainDocs.()
 
-    assert_equal 1, Document.count
+    assert_equal 2, Document.count
     doc = Document.first
     assert_equal '7c7139b9-a228-4691-a4e4-a0c39a6dd615', doc.uuid
     assert_equal "building", doc.section
     assert_equal "APEX", doc.slug
     assert_equal "contributing/README.md", doc.git_path
     assert_equal "Contributing to Exercism", doc.title
     assert_equal "An overview of how to contribute to Exercism", doc.blurb
+    assert_equal 0, doc.position
   end
 
   test "open issue for sync failure when not synced successfully" do
@@ -47,16 +61,24 @@ class Git::SyncMainDocsTest < ActiveSupport::TestCase
     error = StandardError.new "Could not find Concept X"
     Document.any_instance.stubs(:update!).raises(error)
 
-    document = {
+    document_1 = {
       uuid: "7c7139b9-a228-4691-a4e4-a0c39a6dd615",
       section: "contributing",
       slug: "APEX",
       path: "contributing/README.md",
       title: "Contributing to Exercism",
       blurb: "An overview of how to contribute to Exercism"
     }
+    Github::Issue::OpenForDocSyncFailure.expects(:call).with(document_1, :building, error, repo.head_commit.oid)
 
-    Github::Issue::OpenForDocSyncFailure.expects(:call).with(document, :building, error, repo.head_commit.oid)
+    document_2 = {
+      uuid: "d372e903-31fa-4918-a506-e3f939452828",
+      slug: "configlet",
+      path: "building/configlet/README.md",
+      title: "Configlet",
+      blurb: "The canonical specifications for everything on Exercism"
+    }
+    Github::Issue::OpenForDocSyncFailure.expects(:call).with(document_2, :building, error, repo.head_commit.oid)
 
     Git::SyncMainDocs.()
   end

test/commands/git/sync_track_docs_test.rb

@@ -5,14 +5,25 @@ class Git::SyncTrackDocsTest < ActiveSupport::TestCase
     track = create :track, synced_to_git_sha: "d337d99a9cbee14ebd8390d5d1cf86351d604a3a"
     Git::SyncTrackDocs.(track)
 
-    assert_equal 1, Document.count
-    doc = Document.first
-    assert_equal track, doc.track
-    assert_equal '7dce5fef-d759-4292-a2b4-ba3ed65f93d7', doc.uuid
-    assert_equal "testing", doc.slug
-    assert_equal "docs/TESTS.md", doc.git_path
-    assert_equal "Running the tests", doc.title
-    assert_equal "Somewhere over the rainbow, tests run green", doc.blurb
+    assert_equal 2, Document.count
+
+    doc_1 = Document.first
+    assert_equal track, doc_1.track
+    assert_equal '7dce5fef-d759-4292-a2b4-ba3ed65f93d7', doc_1.uuid
+    assert_equal "testing", doc_1.slug
+    assert_equal "docs/TESTS.md", doc_1.git_path
+    assert_equal "Running the tests", doc_1.title
+    assert_equal "Somewhere over the rainbow, tests run green", doc_1.blurb
+    assert_equal 0, doc_1.position
+
+    doc_2 = Document.second
+    assert_equal track, doc_2.track
+    assert_equal 'ae6b8e1c-538e-4431-89e9-c02640e4c3c5', doc_2.uuid
+    assert_equal "learning", doc_2.slug
+    assert_equal "docs/LEARNING.md", doc_2.git_path
+    assert_equal "How to learn C#", doc_2.title
+    assert_equal "An overview of how to get started from scratch with C#", doc_2.blurb
+    assert_equal 1, doc_2.position
   end
 
   test "updates existing docs" do
@@ -22,22 +33,24 @@ class Git::SyncTrackDocsTest < ActiveSupport::TestCase
       slug: "rlly",
       git_path: "incorrect/old.md",
       title: "Very wrong",
-      blurb: "Wrong"
+      blurb: "Wrong",
+      position: 3
 
     Git::SyncTrackDocs.(track)
 
-    assert_equal 1, Document.count
+    assert_equal 2, Document.count
     doc = Document.first
     assert_equal track, doc.track
     assert_equal '7dce5fef-d759-4292-a2b4-ba3ed65f93d7', doc.uuid
     assert_equal "testing", doc.slug
     assert_equal "docs/TESTS.md", doc.git_path
     assert_equal "Running the tests", doc.title
     assert_equal "Somewhere over the rainbow, tests run green", doc.blurb
+    assert_equal 0, doc.position
   end
 
   test "noop if config.json hasn't changed" do
-    track = create :track, synced_to_git_sha: "5f717d8cfc5f588ddff9b1ea5e605f33e70a5c45"
+    track = create :track, synced_to_git_sha: "70714c7d1ac6504c00b8034723da59acb2fb74e7"
 
     Git::Repository.any_instance.expects(:read_json_blob).never
 
@@ -49,6 +62,6 @@ class Git::SyncTrackDocsTest < ActiveSupport::TestCase
 
     Git::SyncTrackDocs.(track, force_sync: true)
 
-    assert_equal 1, Document.count
+    assert_equal 2, Document.count
   end
 end

test/factories/documents.rb

@@ -6,6 +6,7 @@
     git_path { "docs/TESTS.md" }
     section { :contributing }
     title { "Running the Tests" }
+    position { 1 }
   end
 
   trait :track do

test/models/document_test.rb

@@ -19,4 +19,12 @@ class DocumentTest < ActiveSupport::TestCase
       doc.update!(title: 'new-title')
     end
   end
+
+  test "sorted scope sorts by position" do
+    doc_1 = create :document, position: 3
+    doc_2 = create :document, position: 1
+    doc_3 = create :document, position: 2
+
+    assert_equal [doc_2, doc_3, doc_1], Document.sorted
+  end
 end

test/repos/docs/objects/18/dce85a857ceec4504e2a12025c27cb9d44754a

@@ -0,0 +1 @@
+x
+)JMU0�d040031QH��K�L��*��c8cp����'+V���6����{
��

test/repos/docs/objects/6b/351d8b976afc4acaacc9d2b53b261cd30a115e

@@ -0,0 +1 @@
+x
��M�!�Y{���Jm!Y�s�A��n&�`����\`v�o�x/�Z�
����`g�"��I�wv��̒���ol��+v~���;����eĠ�<�1��-��}�"cm�}����n�Sk�<�w��um����[���Z:��!���RL�s��H܈`�ܞ��Q����Tp

test/repos/docs/objects/cc/30dc37e3c7e4a8abc00857d4269432d590ffbd

@@ -0,0 +1,2 @@
+x
}�OK�0�=�S=�m�/��Q� ��$���l���"~w��݃����f��Fh+ �Ӌ���?�x�U_C\�*�L0³�&y�R�s�	O$e�l�2-���	�Sք6i����2�*����yZ������C���k�v��r�i��?c�Yh^q�j�-F��Q|e�
+�`;�1�׭��o���[Ze�Jh�q���&�HJ��c��EVg�<����N��",�bV���ج��1O��\����%��i�Ru�g���#��~s�Ok~������^

test/repos/docs/refs/heads/main

@@ -1 +1 @@
-df5fd1e65ae94870a582ed7dd33adb4f83f127c4
+6b351d8b976afc4acaacc9d2b53b261cd30a115e

test/repos/track/refs/heads/main

@@ -1 +1 @@
-8c68003f3bb1633c60f9f7590a781d99e4cd39f0
+70714c7d1ac6504c00b8034723da59acb2fb74e7