autodoc 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 17b75404749690142753e26acbf21f0a6de60e55
-  data.tar.gz: f80c464a81660e905980d3d7320e13f456bc23ab
+  metadata.gz: 8b183416b270d62f730b447ecf874adbe4a98a3c
+  data.tar.gz: f97bce1b7f34b7cd873027f161c8dbe03fb881fa
 SHA512:
-  metadata.gz: a73209f5f781748ec290b6cbb3a440011badce544d33168ad88853d3ded1c3d440047a00939abb745b4afac35949e3ebb0fb60a1727b534964edddb6ff5151bb
-  data.tar.gz: 0d9b83795d1b0c116804ef78794d9a5de0081cac9f1a6d40cc736be125d8a0fc1637a5854f2cf4f70fd9912fc76fd0429d647ef9f6e3c01dc3472804874597b1
+  metadata.gz: 1d82ae6802bd524f235ac12354426c7938ff6cb03984f6fd7e0b21433b851368b6cb41b0cdf49a3cba9b18c96bac9b83aa03b5db6fd45b03f615dfc4b783fb50
+  data.tar.gz: 6025d431e657cc03a59f80875c1fbaf2b797e5ef0faa5f2c7c60f21a4f75ea2924b29fab7fdfef991e5d20cc209905ef2af35f31b3876e1d574300397d401978

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.2.5
+* add ToC generator
+* use Autodoc.configuration.path to change documents path
+
 ## 0.2.4
 * add Documents class
 

data/README.md

@@ -7,12 +7,7 @@ gem "autodoc", group: :test
 ```
 
 ## Usage
-All request-specs tagged with `:autodoc` will be auto-documented.  
-You must include a HTTP method and request path in the example description.
-
-```
-$ AUTODOC=1 rspec
-```
+All request-specs tagged with `:autodoc` will be auto-documented.
 
 ```ruby
 # spec/requests/recipes_spec.rb
@@ -30,67 +25,18 @@ describe "Recipes" do
 end
 ```
 
-and the following document is generated in [doc/recipes.md](https://github.com/r7kamura/autodoc/blob/master/spec/dummy/doc/recipes.md).
+Run rspec with AUTODOC=1 to generate documents. ([example](https://github.com/r7kamura/autodoc/blob/master/spec/dummy/doc/recipes.md))
 
-<pre>
-## POST /recipes
-Creates a new recipe
-
-```
-POST /recipes
+```sh
+# shell-command
+AUTODOC=1 rspec
 ```
 
-### parameters
-* `name` string (required)
-* `type` integer
-
-### response
-```
-Status: 201
-location: http://www.example.com/recipes/1
-response: 
-{
-  "created_at" => "2013-06-07T08:28:35Z",
-          "id" => 1,
-        "name" => "alice",
-        "type" => 1,
-  "updated_at" => "2013-06-07T08:28:35Z"
-}
-```
-</pre>
-
-## Custom template
-You can customize autodoc's template ([Example](https://github.com/r7kamura/autodoc/blob/master/lib/autodoc/configuration.rb#L18-L33)).  
-Here are avilable variables:
-
-* description
-* example
-* method
-* parameters_section
-* path
-* request
-* request_body_section
-* response
-* response_body
-* response_headers
-* response_status
-
-### Example
-<pre>
-Autodoc.configuration.template = &lt;&lt;-EOF
-  ## &lt;%= method %&gt; &lt;%= path %&gt;
-  &lt;%= description %&gt;
-  &lt;%= parameters_section %&gt;
-  ### request
-  ```
-  &lt;%= method %&gt; &lt;%= path %&gt;
-  ```
-  &lt;%= request_body_section %&gt;
-  ### response
-  ```ruby
-  Status: &lt;%= response_status %&gt;&lt;%= response_headers %&gt;
-  response: &lt;%= response_body %&gt;
-  ```
+### Configuration
+You can configure `Autodoc.configuration` to change its behavior:
 
-EOF
-</pre>
+* path - [String] location to put files (default: ./doc)
+* headers - [Array] keys of documented response header (default: ["Location"])
+* template - [String] ERB template for each document (default: [document.md.erb](https://github.com/r7kamura/autodoc/blob/master/lib/autodoc/templates/document.md.erb))
+* toc_template - [String] ERB template for ToC (default: [toc.md.erb](https://github.com/r7kamura/autodoc/blob/master/lib/autodoc/templates/toc.md.erb))
+* toc - [Boolean] whether to generate toc.md (default: false)

data/lib/autodoc/configuration.rb

@@ -1,21 +1,37 @@
 module Autodoc
   class Configuration
-    attr_writer :headers, :base_path, :template
+    class << self
+      def property(name, &default)
+        define_method(name) do
+          if instance_variable_defined?("@#{name}")
+            instance_variable_get("@#{name}")
+          else
+            instance_variable_set("@#{name}", instance_exec(&default))
+          end
+        end
 
-    def headers
-      @headers ||= %w[Location]
+        attr_writer name
+      end
     end
 
-    def base_path
-      @base_path ||= begin
-        path = Rails.root.join("doc")
-        path += ENV["AUTODOC"] if ENV["AUTODOC"] != "1"
-        path
-      end
+    property :path do
+      "doc"
+    end
+
+    property :headers do
+      %w[Location]
+    end
+
+    property :template do
+      File.read(File.expand_path("../templates/document.md.erb", __FILE__))
+    end
+
+    property :toc_template do
+      File.read(File.expand_path("../templates/toc.md.erb", __FILE__))
     end
 
-    def template
-      @template ||= File.read(File.expand_path("../template.md.erb", __FILE__))
+    property :toc do
+      false
     end
   end
 end

data/lib/autodoc/document.rb

@@ -1,5 +1,6 @@
 require "action_dispatch/http/request"
 require "erb"
+require "pathname"
 
 module Autodoc
   class Document
@@ -11,10 +12,25 @@ module Autodoc
       @context = context
     end
 
+    def pathname
+      @path ||= begin
+        payload = @context.example.file_path.gsub(%r<\./spec/requests/(.+)_spec\.rb>, '\1.md')
+        Pathname.new(Autodoc.configuration.path) + payload
+      end
+    end
+
     def render
       ERB.new(Autodoc.configuration.template, nil, "-").result(binding)
     end
 
+    def title
+      "#{method} #{path}"
+    end
+
+    def identifier
+      title.gsub(" ", "-").gsub(/[:_\/]/, "").downcase
+    end
+
     private
 
     def request

data/lib/autodoc/documents.rb

@@ -1,3 +1,5 @@
+require "pathname"
+
 module Autodoc
   class Documents
     def initialize
@@ -5,16 +7,34 @@ module Autodoc
     end
 
     def append(context)
-      path = context.example.file_path.gsub(%r<\./spec/requests/(.+)_spec\.rb>, '\1.md')
-      key = Autodoc.configuration.base_path + path
-      @table[key] << Autodoc::Document.render(context)
+      document = Autodoc::Document.new(context.clone)
+      @table[document.pathname] << document
     end
 
     def write
+      write_toc if Autodoc.configuration.toc
+      write_documents
+    end
+
+    private
+
+    def write_documents
       @table.each do |pathname, documents|
         pathname.parent.mkpath
-        pathname.open("w") {|file| file << documents.join("\n").rstrip + "\n" }
+        pathname.open("w") {|file| file << documents.map(&:render).join("\n").rstrip + "\n" }
       end
     end
+
+    def write_toc
+      toc_path.open("w") {|file| file << render_toc }
+    end
+
+    def render_toc
+      ERB.new(Autodoc.configuration.toc_template, nil, "-").result(binding)
+    end
+
+    def toc_path
+      Pathname.new(Autodoc.configuration.path) + "toc.md"
+    end
   end
 end

data/lib/autodoc/{template.md.erb → templates/document.md.erb}

@@ -1,5 +1,5 @@
 <%# coding: UTF-8 -%>
-## <%= method %> <%= path %>
+## <%= title %>
 <%= description %>
 <%= parameters_section %>
 ### request

data/lib/autodoc/templates/toc.md.erb

@@ -0,0 +1,11 @@
+<%# coding: UTF-8 -%>
+## Table of Contents
+<% @table.each do |pathname, documents| -%>
+* [<%= pathname.basename %>](<%= pathname.basename %>)
+<% documents.group_by(&:title).each do |title, documents| -%>
+<% documents.each_with_index do |document, index| -%>
+<% suffix = index == 0 ? "" : "-#{index}" -%>
+ * [<%= title %>](<%= "#{pathname.basename}##{document.identifier}#{suffix}" %>)
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/autodoc/version.rb

@@ -1,3 +1,3 @@
 module Autodoc
-  VERSION = "0.2.4"
+  VERSION = "0.2.5"
 end

data/spec/dummy/doc/recipes.md

@@ -23,12 +23,11 @@ response:
   "id": 1,
   "name": "name",
   "type": 1,
-  "created_at": "2013-11-30T13:59:21.061Z",
-  "updated_at": "2013-11-30T13:59:21.061Z"
+  "created_at": "2013-11-30T18:15:08.928Z",
+  "updated_at": "2013-11-30T18:15:08.928Z"
 }
 ```
 
-
 ## POST /recipes
 Creates a new recipe.
 
@@ -54,7 +53,7 @@ response:
   "id": 1,
   "name": "name",
   "type": 1,
-  "created_at": "2013-11-30T13:59:21.072Z",
-  "updated_at": "2013-11-30T13:59:21.072Z"
+  "created_at": "2013-11-30T18:15:08.938Z",
+  "updated_at": "2013-11-30T18:15:08.938Z"
 }
 ```

data/spec/dummy/doc/toc.md

@@ -0,0 +1,4 @@
+## Table of Contents
+* [recipes.md](recipes.md)
+ * [POST /recipes](recipes.md#post-recipes)
+ * [POST /recipes](recipes.md#post-recipes-1)

data/spec/spec_helper.rb

@@ -3,6 +3,9 @@ require File.expand_path("../../spec/dummy/config/environment", __FILE__)
 require "rspec/rails"
 require "rspec/autorun"
 
+Autodoc.configuration.toc = true
+Autodoc.configuration.path = "spec/dummy/doc"
+
 RSpec.configure do |config|
   # If you"re not using ActiveRecord, or you"d prefer not to run each of your
   # examples within a transaction, remove the following line or assign false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: autodoc
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Ryo Nakamura
@@ -113,7 +113,8 @@ files:
 - lib/autodoc/document.rb
 - lib/autodoc/documents.rb
 - lib/autodoc/rspec.rb
-- lib/autodoc/template.md.erb
+- lib/autodoc/templates/document.md.erb
+- lib/autodoc/templates/toc.md.erb
 - lib/autodoc/version.rb
 - spec/dummy/Rakefile
 - spec/dummy/app/assets/javascripts/application.js
@@ -144,6 +145,7 @@ files:
 - spec/dummy/db/migrate/20130607075126_create_recipes.rb
 - spec/dummy/db/schema.rb
 - spec/dummy/doc/recipes.md
+- spec/dummy/doc/toc.md
 - spec/dummy/lib/assets/.gitkeep
 - spec/dummy/log/.gitkeep
 - spec/dummy/public/404.html
@@ -207,6 +209,7 @@ test_files:
 - spec/dummy/db/migrate/20130607075126_create_recipes.rb
 - spec/dummy/db/schema.rb
 - spec/dummy/doc/recipes.md
+- spec/dummy/doc/toc.md
 - spec/dummy/lib/assets/.gitkeep
 - spec/dummy/log/.gitkeep
 - spec/dummy/public/404.html