From 70448da8ec1784ac03dbb3e9bcf50b14b8ad5f4c Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Fri, 27 May 2016 09:00:14 +1000 Subject: [PATCH 1/7] Fixed up sections for slate format generation and made a better default template name. --- lib/rspec_api_documentation.rb | 1 + .../views/slate_example.rb | 10 ++++-- .../views/slate_index.rb | 6 ++++ .../writers/slate_writer.rb | 31 +++++++++++++++---- 4 files changed, 39 insertions(+), 9 deletions(-) create mode 100644 lib/rspec_api_documentation/views/slate_index.rb diff --git a/lib/rspec_api_documentation.rb b/lib/rspec_api_documentation.rb index 569ff90d..e50d672d 100644 --- a/lib/rspec_api_documentation.rb +++ b/lib/rspec_api_documentation.rb @@ -57,6 +57,7 @@ module Views autoload :TextileExample autoload :MarkdownIndex autoload :MarkdownExample + autoload :SlateIndex autoload :SlateExample end diff --git a/lib/rspec_api_documentation/views/slate_example.rb b/lib/rspec_api_documentation/views/slate_example.rb index 1d23ef69..5836c80e 100644 --- a/lib/rspec_api_documentation/views/slate_example.rb +++ b/lib/rspec_api_documentation/views/slate_example.rb @@ -18,10 +18,14 @@ def explanation_with_linebreaks 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| + sections.each do |section| + file.write "# #{section[:resource_name]}\n\n" + end + + section[:examples].examples.sort_by!(&:description) unless configuration.keep_source_order + + section[:examples].examples.each do |example| markup_example = markup_example_class.new(example, configuration) file.write markup_example.render end diff --git a/lib/rspec_api_documentation/views/slate_index.rb b/lib/rspec_api_documentation/views/slate_index.rb new file mode 100644 index 00000000..f3d518ef --- /dev/null +++ b/lib/rspec_api_documentation/views/slate_index.rb @@ -0,0 +1,6 @@ +module RspecApiDocumentation + module Views + class SlateIndex < MarkdownIndex + end + end +end diff --git a/lib/rspec_api_documentation/writers/slate_writer.rb b/lib/rspec_api_documentation/writers/slate_writer.rb index 758a6b37..edd020f9 100644 --- a/lib/rspec_api_documentation/writers/slate_writer.rb +++ b/lib/rspec_api_documentation/writers/slate_writer.rb @@ -2,28 +2,47 @@ 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\n} + file.write %Q{---\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 From fca436c51b4976c0589b5034042700a53193aeb7 Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Fri, 27 May 2016 11:55:37 +1000 Subject: [PATCH 2/7] Adding JSON as default language tab. --- lib/rspec_api_documentation/writers/slate_writer.rb | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/rspec_api_documentation/writers/slate_writer.rb b/lib/rspec_api_documentation/writers/slate_writer.rb index edd020f9..6ea7a5ea 100644 --- a/lib/rspec_api_documentation/writers/slate_writer.rb +++ b/lib/rspec_api_documentation/writers/slate_writer.rb @@ -22,8 +22,10 @@ def write File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file| file.write %Q{---\n} - file.write %Q{title: "#{configuration.api_name}"\n\n} - 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| From 132e02eba497cb1f6802ed82d981e45c3d8f0401 Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Fri, 27 May 2016 11:57:30 +1000 Subject: [PATCH 3/7] Moved explanation up to top of endpoint documentatino and changed curl to use shell formatter in slate. --- .../views/slate_example.rb | 16 +++---- spec/views/slate_example_spec.rb | 44 ------------------- .../slate_example.mustache | 17 ++++--- 3 files changed, 13 insertions(+), 64 deletions(-) diff --git a/lib/rspec_api_documentation/views/slate_example.rb b/lib/rspec_api_documentation/views/slate_example.rb index 5836c80e..47f0bb87 100644 --- a/lib/rspec_api_documentation/views/slate_example.rb +++ b/lib/rspec_api_documentation/views/slate_example.rb @@ -6,12 +6,6 @@ def initialize(example, configuration) 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 "
" - end - def explanation_with_linebreaks explanation.gsub "\n", "
\n" end @@ -21,13 +15,13 @@ def write sections.each do |section| file.write "# #{section[:resource_name]}\n\n" - end - section[:examples].examples.sort_by!(&:description) unless configuration.keep_source_order + section[:examples].examples.sort_by!(&:description) unless configuration.keep_source_order - section[:examples].examples.each do |example| - markup_example = markup_example_class.new(example, configuration) - file.write markup_example.render + section[:examples].examples.each do |example| + markup_example = markup_example_class.new(example, configuration) + file.write markup_example.render + end end end end diff --git a/spec/views/slate_example_spec.rb b/spec/views/slate_example_spec.rb index 0a1b47c5..e456fc91 100644 --- a/spec/views/slate_example_spec.rb +++ b/spec/views/slate_example_spec.rb @@ -10,50 +10,6 @@ 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('
') - 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 b' - end - end - - context 'tabs' do - let(:string) { "a\tb" } - - it 'replaces them with two nonbreaking spaces' do - expect(subject).to be == 'a  b' - end - end - - context 'backslashes' do - let(:string) { 'a\\b'} - - it 'replaces them with an HTML entity' do - expect(subject).to be == 'a\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" diff --git a/templates/rspec_api_documentation/slate_example.mustache b/templates/rspec_api_documentation/slate_example.mustache index 66262d62..d74400bc 100644 --- a/templates/rspec_api_documentation/slate_example.mustache +++ b/templates/rspec_api_documentation/slate_example.mustache @@ -1,5 +1,10 @@ ## {{ description }} +{{# explanation }} + +{{{ explanation_with_linebreaks }}} +{{/ explanation }} + ### Request #### Endpoint @@ -13,11 +18,6 @@ `{{ http_method }} {{ route }}` -{{# explanation }} - -{{{ explanation_with_linebreaks }}} -{{/ explanation }} - #### Parameters {{# requests}} @@ -78,9 +78,8 @@ None known. {{/ has_response_fields? }} {{# curl }} - -### cURL - -{{{ curl_with_linebreaks }}} +```shell +{{{ curl }}} +``` {{/ curl }} {{/ requests}} From d23e7940213fc8cb6bb3b75ccc0fcb23adad3652 Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Fri, 27 May 2016 11:58:14 +1000 Subject: [PATCH 4/7] Changed explanation formatter to not add automatic
in text. --- lib/rspec_api_documentation/views/slate_example.rb | 4 ---- spec/views/slate_example_spec.rb | 7 ------- templates/rspec_api_documentation/slate_example.mustache | 3 +-- 3 files changed, 1 insertion(+), 13 deletions(-) diff --git a/lib/rspec_api_documentation/views/slate_example.rb b/lib/rspec_api_documentation/views/slate_example.rb index 47f0bb87..4d2c178c 100644 --- a/lib/rspec_api_documentation/views/slate_example.rb +++ b/lib/rspec_api_documentation/views/slate_example.rb @@ -6,10 +6,6 @@ def initialize(example, configuration) self.template_name = "rspec_api_documentation/slate_example" end - def explanation_with_linebreaks - explanation.gsub "\n", "
\n" - end - def write File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file| diff --git a/spec/views/slate_example_spec.rb b/spec/views/slate_example_spec.rb index e456fc91..a834ced7 100644 --- a/spec/views/slate_example_spec.rb +++ b/spec/views/slate_example_spec.rb @@ -10,11 +10,4 @@ let(:configuration) { RspecApiDocumentation::Configuration.new } let(:slate_example) { described_class.new(rad_example, configuration) } - 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", "
\n") - end - end end diff --git a/templates/rspec_api_documentation/slate_example.mustache b/templates/rspec_api_documentation/slate_example.mustache index d74400bc..4b31cd0d 100644 --- a/templates/rspec_api_documentation/slate_example.mustache +++ b/templates/rspec_api_documentation/slate_example.mustache @@ -1,8 +1,7 @@ ## {{ description }} {{# explanation }} - -{{{ explanation_with_linebreaks }}} +{{{ explanation }}} {{/ explanation }} ### Request From a734d94c7fa0e9a9edcbd71249d5dbe0c2f96102 Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Fri, 27 May 2016 18:20:35 +1000 Subject: [PATCH 5/7] Updated cucumber spec. --- features/slate_documentation.feature | 38 +++++++++++++++------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/features/slate_documentation.feature b/features/slate_documentation.feature index c4be5499..8eb557cf 100644 --- a/features/slate_documentation.feature +++ b/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 - - curl "http://localhost:3000/orders" -X GET \
  -H "Host: example.org" \
  -H "Cookie: " + ```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 - - 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: " + ```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 """ From 54ce18d46dbcf9b4435bbc97b9f49ec206ca50e0 Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Fri, 27 May 2016 18:20:51 +1000 Subject: [PATCH 6/7] Updated slate_writer_spec.rb to verify correct file created. --- spec/writers/slate_writer_spec.rb | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/spec/writers/slate_writer_spec.rb b/spec/writers/slate_writer_spec.rb index 9e6e33b0..3f121b52 100644 --- a/spec/writers/slate_writer_spec.rb +++ b/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) } From 22285704de53ff7288c49a3a995ceda8bcd575b7 Mon Sep 17 00:00:00 2001 From: Rob Pocklington Date: Thu, 2 Jun 2016 08:17:53 +1000 Subject: [PATCH 7/7] Removed redundant 'write' method from slate example. --- .../views/slate_example.rb | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/lib/rspec_api_documentation/views/slate_example.rb b/lib/rspec_api_documentation/views/slate_example.rb index 4d2c178c..0327ba9a 100644 --- a/lib/rspec_api_documentation/views/slate_example.rb +++ b/lib/rspec_api_documentation/views/slate_example.rb @@ -5,22 +5,6 @@ def initialize(example, configuration) super self.template_name = "rspec_api_documentation/slate_example" end - - def write - File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file| - - sections.each do |section| - file.write "# #{section[:resource_name]}\n\n" - - section[:examples].examples.sort_by!(&:description) unless configuration.keep_source_order - - section[:examples].examples.each do |example| - markup_example = markup_example_class.new(example, configuration) - file.write markup_example.render - end - end - end - end end end end