Merge pull request #287 from rpocklin/feature/slate-generator-tweaks

Feature/slate generator tweaks

Author: oestrich

features/slate_documentation.feature

@@ -144,10 +144,11 @@ Feature: Generate Slate documentation from test examples
     And   the exit status should be 0
 
   Scenario: Example 'Getting a list of orders' docs should look like we expect
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
     ## Getting a list of orders
 
+
     ### Request
 
     #### Endpoint
@@ -159,7 +160,6 @@ Feature: Generate Slate documentation from test examples
 
     `GET /orders`
 
-
     #### Parameters
 
 
@@ -202,17 +202,20 @@ Feature: Generate Slate documentation from test examples
     | page | Current page |
 
 
-
-    ### cURL
-
-    <code>curl&nbsp;"http://localhost:3000/orders"&nbsp;-X&nbsp;GET&nbsp;&#92;<br>&nbsp;&nbsp;-H&nbsp;"Host:&nbsp;example.org"&nbsp;&#92;<br>&nbsp;&nbsp;-H&nbsp;"Cookie:&nbsp;"</code>
+    ```shell
+    curl "http://localhost:3000/orders" -X GET \
+    	-H "Host: example.org" \
+    	-H "Cookie: "
     """
 
   Scenario: Example 'Creating an order' docs should look like we expect
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
+    # Orders
+
     ## Creating an order
 
+
     ### Request
 
     #### Endpoint
@@ -225,7 +228,6 @@ Feature: Generate Slate documentation from test examples
 
     `POST /orders`
 
-
     #### Parameters
 
 
@@ -253,38 +255,40 @@ Feature: Generate Slate documentation from test examples
 
 
 
-
-    ### cURL
-
-    <code>curl&nbsp;"http://localhost:3000/orders"&nbsp;-d&nbsp;'name=Order+3&amount=33.0'&nbsp;-X&nbsp;POST&nbsp;&#92;<br>&nbsp;&nbsp;-H&nbsp;"Host:&nbsp;example.org"&nbsp;&#92;<br>&nbsp;&nbsp;-H&nbsp;"Content-Type:&nbsp;application/x-www-form-urlencoded"&nbsp;&#92;<br>&nbsp;&nbsp;-H&nbsp;"Cookie:&nbsp;"</code>
+    ```shell
+    curl "http://localhost:3000/orders" -d 'name=Order+3&amount=33.0' -X POST \
+    	-H "Host: example.org" \
+    	-H "Content-Type: application/x-www-form-urlencoded" \
+    	-H "Cookie: "
+    ```
     """
 
   Scenario: Example 'Deleting an order' docs should be created
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
     ## Deleting an order
     """
 
   Scenario: Example 'Getting a list of orders' docs should be created
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
     ## Getting a list of orders
     """
 
   Scenario: Example 'Getting a specific order' docs should be created
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
     ## Getting a specific order
     """
 
   Scenario: Example 'Updating an order' docs should be created
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
     ## Updating an order
     """
 
   Scenario: Example 'Getting welcome message' docs should be created
-    Then the file "doc/api/_generated_examples.markdown" should contain:
+    Then the file "doc/api/index.html.md" should contain:
     """
     ## Getting welcome message
     """

lib/rspec_api_documentation.rb

@@ -57,6 +57,7 @@ module Views
     autoload :TextileExample
     autoload :MarkdownIndex
     autoload :MarkdownExample
+    autoload :SlateIndex
     autoload :SlateExample
   end
 

lib/rspec_api_documentation/views/slate_example.rb

@@ -5,28 +5,6 @@ def initialize(example, configuration)
         super
         self.template_name = "rspec_api_documentation/slate_example"
       end
-
-      def curl_with_linebreaks
-        requests.map {|request| request[:curl].lines }.flatten.map do |line|
-          line.rstrip.gsub("\t", '  ').gsub(' ', ' ').gsub('\\', '\')
-        end.join "<br>"
-      end
-
-      def explanation_with_linebreaks
-        explanation.gsub "\n", "<br>\n"
-      end
-
-      def write
-        File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file|
-          file.write "# #{configuration.api_name}\n\n"
-          index.examples.sort_by!(&:description) unless configuration.keep_source_order
-
-          index.examples.each do |example|
-            markup_example = markup_example_class.new(example, configuration)
-            file.write markup_example.render
-          end
-        end
-      end
     end
   end
 end

lib/rspec_api_documentation/views/slate_index.rb

@@ -0,0 +1,6 @@
+module RspecApiDocumentation
+  module Views
+    class SlateIndex < MarkdownIndex
+    end
+  end
+end

lib/rspec_api_documentation/writers/slate_writer.rb

@@ -2,28 +2,49 @@ module RspecApiDocumentation
   module Writers
 
     class SlateWriter < MarkdownWriter
-      FILENAME = '_generated_examples'
+      EXTENSION = 'html.md'
+      FILENAME = 'index'
 
       def self.clear_docs(docs_dir)
         FileUtils.mkdir_p(docs_dir)
         FileUtils.rm Dir[File.join docs_dir, "#{FILENAME}.*"]
       end
 
+      def markup_index_class
+        RspecApiDocumentation::Views::SlateIndex
+      end
+
       def markup_example_class
         RspecApiDocumentation::Views::SlateExample
       end
 
       def write
         File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file|
-          file.write "# #{configuration.api_name}\n\n"
-          index.examples.sort_by!(&:description) unless configuration.keep_source_order
 
-          index.examples.each do |example|
-            markup_example = markup_example_class.new(example, configuration)
-            file.write markup_example.render
+          file.write %Q{---\n}
+          file.write %Q{title: "#{configuration.api_name}"\n}
+          file.write %Q{language_tabs:\n}
+          file.write %Q{  - json: JSON\n}
+          file.write %Q{---\n\n}
+
+          IndexHelper.sections(index.examples, @configuration).each do |section|
+
+            file.write "# #{section[:resource_name]}\n\n"
+            section[:examples].sort_by!(&:description) unless configuration.keep_source_order
+
+            section[:examples].each do |example|
+              markup_example = markup_example_class.new(example, configuration)
+              file.write markup_example.render
+            end
+
           end
+
         end
       end
+
+      def extension
+        EXTENSION
+      end
     end
   end
 end

spec/views/slate_example_spec.rb

@@ -10,55 +10,4 @@
   let(:configuration) { RspecApiDocumentation::Configuration.new }
   let(:slate_example) { described_class.new(rad_example, configuration) }
 
-  describe '#curl_with_linebreaks' do
-    subject { slate_example.curl_with_linebreaks }
-
-    before(:each) { allow(slate_example).to receive(:requests).and_return requests }
-
-    context 'marshaling' do
-      let(:requests) { [{curl: 'One'}, {curl: "Two \nThree" }, {curl: 'Four   '}] }
-
-      it 'joins all the Curl requests with linebreaks, stripping trailing whitespace' do
-        expect(subject).to be == [
-          'One', 'Two', 'Three', 'Four'
-        ].join('<br>')
-      end
-    end
-
-    context 'escaping' do
-      let(:requests) { [{curl: string}] }
-
-      context 'spaces' do
-        let(:string) { 'a b' }
-
-        it 'replaces them with nonbreaking spaces' do
-          expect(subject).to be == 'a&nbsp;b'
-        end
-      end
-
-      context 'tabs' do
-        let(:string) { "a\tb" }
-
-        it 'replaces them with two nonbreaking spaces' do
-          expect(subject).to be == 'a&nbsp;&nbsp;b'
-        end
-      end
-
-      context 'backslashes' do
-        let(:string) { 'a\\b'}
-
-        it 'replaces them with an HTML entity' do
-          expect(subject).to be == 'a&#92;b'
-        end
-      end
-    end
-  end
-
-  describe '#explanation_with_linebreaks' do
-    it 'returns the explanation with HTML linebreaks' do
-      explanation = "Line 1\nLine 2\nLine 3\Line 4"
-      allow(slate_example).to receive(:explanation).and_return explanation
-      expect(slate_example.explanation_with_linebreaks).to be == explanation.gsub("\n", "<br>\n")
-    end
-  end
 end

spec/writers/slate_writer_spec.rb

@@ -15,6 +15,23 @@
     end
   end
 
+  describe "#write" do
+    let(:writer) { described_class.new(index, configuration) }
+
+    before do
+      template_dir = File.join(configuration.template_path, "rspec_api_documentation")
+      FileUtils.mkdir_p(template_dir)
+      File.open(File.join(template_dir, "markdown_index.mustache"), "w+") { |f| f << "{{ mustache }}" }
+      FileUtils.mkdir_p(configuration.docs_dir)
+    end
+
+    it "should write the index" do
+      writer.write
+      index_file = File.join(configuration.docs_dir, "index.html.md")
+      expect(File.exists?(index_file)).to be_truthy
+    end
+  end
+
   context 'instance methods' do
     let(:writer) { described_class.new(index, configuration) }
 

templates/rspec_api_documentation/slate_example.mustache

@@ -1,5 +1,9 @@
 ## {{ description }}
 
+{{# explanation }}
+{{{ explanation }}}
+{{/ explanation }}
+
 ### Request
 
 #### Endpoint
@@ -13,11 +17,6 @@
 
 `{{ http_method }} {{ route }}`
 
-{{# explanation }}
-
-{{{ explanation_with_linebreaks }}}
-{{/ explanation }}
-
 #### Parameters
 
 {{# requests}}
@@ -78,9 +77,8 @@ None known.
 {{/ has_response_fields? }}
 
 {{# curl }}
-
-### cURL
-
-<code>{{{ curl_with_linebreaks }}}</code>
+```shell
+{{{ curl }}}
+```
 {{/ curl }}
 {{/ requests}}