documentary 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ead34348f2423c01e41ed552a763454622c704a
-  data.tar.gz: 30fe4374be10722e56c6d9f24f1ed532fb51752d
+  metadata.gz: 0cd2c7bca305075774d21b7fe6aaa73a5c8adc4c
+  data.tar.gz: 7de58c814f31b1c2c0ae0d17ad21b2656143b0a8
 SHA512:
-  metadata.gz: 405f93a4c0352eefbc7c9f98cfaecd597a813c5413bff0803abf7f6d7b04e4d5a5a7e17ad0a57d6d564bf2c845d72a8301cc3d6b2cefee60f566e7cf4bc1c186
-  data.tar.gz: 649f53fa435e6aae7e299057340545d2488e89302ac0b233a70709414c06f347d2982d71e34cdb3620c4e53cde41c0b6ea3ea26dfacb84a9acbf0c6ea1ced143
+  metadata.gz: a0153f941656a662f53108687263880f8774aa9aa4a5df018b44a11776525482912cc8110c608f8dd70f5a4503ddb8dde30b851e1046002924023898bff99c75
+  data.tar.gz: afb5123c1d0b2c7e1bb4fb40ae5234df835401a5ca256a742ee00cde3717aa935377cbdc36ed80c6513840bb723a2711a91c50bfaf26694e31fb5efdc770190d

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    documentary (0.1.0)
+    documentary (0.1.1)
       activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.2.0)
+    activesupport (4.2.6)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
@@ -15,10 +15,10 @@ GEM
       tzinfo (~> 1.1)
     byebug (9.0.5)
     i18n (0.7.0)
-    json (1.8.2)
+    json (1.8.3)
     minitest (5.4.3)
     rake (10.3.2)
-    thread_safe (0.3.4)
+    thread_safe (0.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
 

data/README.md

@@ -6,20 +6,19 @@ A simple tool that will allow you to generate API runnable documentation quickly
 >
 > -- <cite>Kathy Sierra</cite>
 
-## Todos
-
-* [X] Build the parser
-* [X] Integration Test
-* [X] Title Blocks
-* [X] Ordering
-* [X] Resource Blocks
-* [X] Endpoint Blocks
-* [X] Introduce Generation config
-* [X] Introduce view helpers
-* [ ] CLI design
-* [ ] TOC for documentation
-* [ ] Start being more strict on specification for MD generation?
-* [ ] Create testing suite
+[Example of the documentation generated](https://gist.github.com/bangline/edeb0201b13b2721be3764f5fa0c76d5)
+
+## Installation
+
+```
+gem install documentary
+```
+
+Or in your Gemfile:
+
+```
+gem 'documentary'
+```
 
 ## Specification
 

data/documentary.gemspec

@@ -5,7 +5,8 @@ Gem::Specification.new do |s|
   s.name          = 'documentary'
   s.version       = Documentary::VERSION
   s.summary       = 'Documentary'
-  s.description   = 'Simple, useable, runnable API documentation'
+  s.homepage      = 'https://github.com/bangline/documentary'
+  s.description   = 'Simple, useable, maintainable API documentation'
   s.authors       = ['Dave Kennedy']
   s.email         = 'david@bangline.co.uk'
   s.files         = `git ls-files`.split("\n")

data/lib/default_layout.erb

@@ -1,5 +1,9 @@
 # <%= project_name %>
 
+## Contents
+
+<%= toc %>
+
 <%= title_blocks %>
 <%= resource_blocks %>
 <%= endpoint_blocks %>

data/lib/documentary/version.rb

@@ -1,3 +1,3 @@
 module Documentary
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/documentary/view/helpers.rb

@@ -2,6 +2,21 @@ module Documentary
   module View
     require 'stringio'
 
+    def toc
+      io = StringIO.new
+      io.puts "### [Resources](#resources)"
+      io.puts new_line
+      docblocks.resources.each do |resource|
+        io.puts "* #{link_to(resource.title)}"
+      end
+      io.puts new_line
+      io.puts "### [Endpoints](#endpoints)"
+      docblocks.endpoints.each do |endpoint|
+        io.puts "* #{link_to(endpoint.title)}"
+      end
+      io.string
+    end
+
     def title_blocks
       io = StringIO.new
       docblocks.title_blocks.each do |title_block|
@@ -15,10 +30,10 @@ module Documentary
 
     def resource_blocks
       io = StringIO.new
-      io.puts '## Resources'
+      io.puts "## #{link_to('Resources')}"
       io.puts new_line
       docblocks.resources.each do |resource|
-        io.puts "### #{resource.title}"
+        io.puts "### #{link_to(resource.title)}"
         io.puts new_line
         io.puts resource.description
         io.puts new_line
@@ -30,10 +45,10 @@ module Documentary
 
     def endpoint_blocks
       io = StringIO.new
-      io.puts '## Endpoints'
+      io.puts "## #{link_to('Endpoints')}"
       io.puts new_line
       docblocks.endpoints.each do |endpoint|
-        io.puts "### #{endpoint.title}"
+        io.puts "### #{link_to(endpoint.title)}"
         io.puts new_line
         io.puts endpoint.notes if endpoint.notes
         io.puts new_line
@@ -85,6 +100,10 @@ module Documentary
 
     private
 
+      def link_to(title)
+        "[#{title}](##{title.downcase.gsub(' ', '-')})"
+      end
+
       def resource_attributes(resource, io)
         io.puts '#### Attributes'
         io.puts new_line

data/test/integration_helper.rb

@@ -16,11 +16,11 @@ class Minitest::Test
   end
 
   def assert_has_resource_title
-    assert_includes generated_docs, "## Resources"
+    assert_includes generated_docs, "## [Resources](#resources)"
   end
 
   def assert_has_enpoints_title
-    assert_includes generated_docs, "## Endpoints"
+    assert_includes generated_docs, "## [Endpoints](#endpoints)"
   end
 
   def assert_has_third_level_heading(heading)
@@ -28,10 +28,10 @@ class Minitest::Test
   end
 
   def assert_content_for_resource(resource, content)
-    assert_match /### #{resource}\n\n#{content}/, generated_docs
+    assert_match /### \[#{resource}\]\(##{resource.downcase.gsub(' ', '-')}\)\n\n#{content}/, generated_docs
   end
 
   def assert_table_entry_for_resource(resource, row_content)
     assert_match /### #{resource}[.+]#{row_content[:name]} | #{row_content[:required]} | #{row_content[:type]}/, generated_docs
   end
-end
+end

data/test/integration_test.rb

@@ -35,7 +35,7 @@ class Documentary::IntegrationTest < MiniTest::Test
   end
 
   test 'named resources are correctly generated' do
-    assert_has_third_level_heading 'A Resource'
+    assert_includes generated_docs, '### [A Resource](#a-resource)'
   end
 
   test 'named resources descriptions are correctly generated' do
@@ -51,7 +51,7 @@ class Documentary::IntegrationTest < MiniTest::Test
   end
 
   test 'named enpoints are correctly generated' do
-    assert_includes generated_docs, '### List endpoint'
+    assert_includes generated_docs, '### [List endpoint](#list-endpoint)'
   end
 
   test 'enpoint url is generated' do
@@ -77,4 +77,12 @@ class Documentary::IntegrationTest < MiniTest::Test
     assert_includes generated_docs, "#### Example Response\n\n```\n"
     assert_includes generated_docs, "\"page\": 1,\n"
   end
+
+  test 'TOC is generated' do
+    assert_includes generated_docs, "## Contents\n"
+    assert_includes generated_docs, "### [Resources](#resources)\n"
+    assert_includes generated_docs, "* [A Resource](#a-resource)\n"
+    assert_includes generated_docs, "### [Endpoints](#endpoints)\n"
+    assert_includes generated_docs, "* [List endpoint](#list-endpoint)\n"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: documentary
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Dave Kennedy
@@ -52,7 +52,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 10.3.2
-description: Simple, useable, runnable API documentation
+description: Simple, useable, maintainable API documentation
 email: david@bangline.co.uk
 executables:
 - documentary