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 """ 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..0327ba9a 100644 --- a/lib/rspec_api_documentation/views/slate_example.rb +++ b/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 "
" - end - - def explanation_with_linebreaks - explanation.gsub "\n", "
\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 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..6ea7a5ea 100644 --- a/lib/rspec_api_documentation/writers/slate_writer.rb +++ b/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 diff --git a/spec/views/slate_example_spec.rb b/spec/views/slate_example_spec.rb index 0a1b47c5..a834ced7 100644 --- a/spec/views/slate_example_spec.rb +++ b/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('
') - 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" - 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/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) } diff --git a/templates/rspec_api_documentation/slate_example.mustache b/templates/rspec_api_documentation/slate_example.mustache index 66262d62..4b31cd0d 100644 --- a/templates/rspec_api_documentation/slate_example.mustache +++ b/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 - -{{{ curl_with_linebreaks }}} +```shell +{{{ curl }}} +``` {{/ curl }} {{/ requests}}