Add latest changes from gitlab-org/gitlab@master

2 files changed, 61 insertions, 25 deletions

diff --git a/scripts/lib/glfm/parse_examples.rb b/scripts/lib/glfm/parse_examples.rb
index 1c6afb800c3..051cbdc7941 100644
--- a/scripts/lib/glfm/parse_examples.rb
+++ b/scripts/lib/glfm/parse_examples.rb
@@ -13,7 +13,11 @@
 # 1. Capture all nested headers, not just the most recent.
 # 2. Raise an exception if an unexpected state is encountered.
 #
-# Comments indicate where changes or additions were made.
+# Comments indicate where changes, deletions, or additions were made.
+#
+# See more detailed documentation of rules regarding the handling of headers
+# in the comments at the top of `Glfm::UpdateExampleSnapshots#add_example_names`,
+# in `scripts/lib/glfm/update_example_snapshots.rb`
 module Glfm
   module ParseExamples
     REGULAR_TEXT = 0
@@ -37,6 +41,7 @@ module Glfm
 
       h1_regex = /\A# / # new logic compared to original Python code
       h2_regex = /\A## / # new logic compared to original Python code
+      h3_regex = /\A### / # new logic compared to original Python code
       header_regex = /\A#+ / # Added beginning of line anchor to original Python code
 
       spec_txt_lines.each do |line|
@@ -51,22 +56,29 @@ module Glfm
           state = REGULAR_TEXT
           example_number += 1
           end_line = line_number
-          unless extensions.include?('disabled')
-            tests <<
-              {
-                markdown: markdown_lines.join.tr('→', "\t"),
-                html: html_lines.join.tr('→', "\t"),
-                example: example_number,
-                start_line: start_line,
-                end_line: end_line,
-                section: headertext,
-                extensions: extensions,
-                headers: headers.dup # new logic compared to original Python code
-              }
-            start_line = 0
-            markdown_lines = []
-            html_lines = []
-          end
+
+          # NOTE: The original implementation completely excludes disabled examples, but we need
+          # to include them in order to correctly count the header numbering, so we set a flag
+          # instead. This will need to be accounted for when we run conformance testing.
+
+          # unless extensions.include?('disabled') # commented logic compared to original Python code
+          tests <<
+            {
+              markdown: markdown_lines.join.tr('→', "\t"),
+              html: html_lines.join.tr('→', "\t"),
+              example: example_number,
+              start_line: start_line,
+              end_line: end_line,
+              section: headertext,
+              extensions: extensions,
+              headers: headers.dup, # new logic compared to original Python code
+              disabled: extensions.include?('disabled') # new logic compared to original Python code
+            }
+          # end # commented logic compared to original Python code
+
+          start_line = 0
+          markdown_lines = []
+          html_lines = []
         elsif stripped_line == "."
           # Else if the example divider line...
           state = HTML_OUTPUT
@@ -80,16 +92,27 @@ module Glfm
           html_lines.append(line)
         elsif state == REGULAR_TEXT && line =~ header_regex
           # Else if we are in regular text and it is a header line
-          # NOTE: This assumes examples are only nested up to 2 levels deep (H2)
+          # NOTE: This assumes examples are within the section under
+          # Heading level 2 with Heading levels above 2 ignored
 
           # Extract the header text from the line
           headertext = line.gsub(header_regex, '').strip
 
-          # reset the headers array if we found a new H1
-          headers = [] if line =~ h1_regex # new logic compared to original Python code
+          # The 'headers' array is new logic compared to the original Python code
 
-          # pop the last entry from the headers array if we found a new H2
-          headers.pop if headers.length == 2 && line =~ h2_regex # new logic compared to original Python code
+          # reset the headers array if we found a new H1
+          headers = [] if line =~ h1_regex
+
+          if headers.length == 2 && line =~ h2_regex
+            # pop the last entry from the headers array if we are in an H2 and found a new H2
+            headers.pop
+          elsif headers.length == 3 && line =~ h3_regex
+            # pop the last entry from the headers array if we are in an H3 and found a new H3
+            headers.pop
+          elsif headers.length == 3 && line =~ h2_regex
+            # pop the last two entries from the headers array if we are in an H3 and found a new H2
+            headers.pop(2)
+          end
 
           # push the new header text to the headers array
           headers << headertext # New logic compared to original Python code
diff --git a/scripts/lib/glfm/update_example_snapshots.rb b/scripts/lib/glfm/update_example_snapshots.rb
index 10529b1f974..893d8d9c014 100644
--- a/scripts/lib/glfm/update_example_snapshots.rb
+++ b/scripts/lib/glfm/update_example_snapshots.rb
@@ -40,18 +40,27 @@ module Glfm
 
       add_example_names(all_examples)
 
+      reject_disabled_examples(all_examples)
+
       write_snapshot_example_files(all_examples, skip_static_and_wysiwyg: skip_static_and_wysiwyg)
     end
 
     private
 
     def add_example_names(all_examples)
-      # NOTE: This method assumes:
+      # NOTE: This method and the parse_examples method assume:
       # 1. Section 2 is the first section which contains examples
-      # 2. Examples are always nested exactly than 2 levels deep in an H2
-      # 3. We assume that the Appendix doesn't ever contain any examples, so it doesn't show up
+      # 2. Examples are always nested exactly 2 levels deep in an H2
+      # 3. There may exist H3 headings with no examples (e.g. "Motivation" in the GLFM spec.txt)
+      # 4. The Appendix doesn't ever contain any examples, so it doesn't show up
       #    in the H1 header count. So, even though due to the concatenation it appears before the
       #    GitLab examples sections, it doesn't result in their header counts being off by +1.
+      # 5. If an example contains the 'disabled' string extension, it is skipped (and will thus
+      #    result in a skip in the `spec_txt_example_position`). This behavior is taken from the
+      #    GFM `spec_test.py` script (but it's NOT in the original CommonMark `spec_test.py`).
+      # 6. If a section contains ONLY disabled examples, the section numbering will still be
+      #    incremented to match the rendered HTML specification section numbering.
+      # 7. Every H2 must contain at least one example, but it is allowed that they are all disabled.
 
       h1_count = 1 # examples start in H1 section 2; section 1 is the overview with no examples.
       h2_count = 0
@@ -86,6 +95,10 @@ module Glfm
       end
     end
 
+    def reject_disabled_examples(all_examples)
+      all_examples.reject! { |example| example[:disabled] }
+    end
+
     def write_snapshot_example_files(all_examples, skip_static_and_wysiwyg:)
       output("Reading #{GLFM_EXAMPLE_STATUS_YML_PATH}...")
       glfm_examples_statuses = YAML.safe_load(File.open(GLFM_EXAMPLE_STATUS_YML_PATH))