fdoc 0.2.1 → 0.2.2

data/README.md

@@ -18,26 +18,32 @@ Add fdoc to your Gemfile.
 
     gem 'fdoc'
 
-Tell fdoc where to look for .fdoc files. By default, fdoc will look in `docs/fdoc`, but you can change this behavior to look anywhere. This fits best in something like a spec\_helper file.
+Tell fdoc where to look for `.fdoc` files. By default, fdoc will look in `docs/fdoc`, but you can change this behavior to look anywhere. This fits best in something like a spec\_helper file.
 
-    require 'fdoc'
+```ruby
+require 'fdoc'
 
-    Fdoc.service_path = "path/to/your/fdocs"
+Fdoc.service_path = "path/to/your/fdocs"
+```
 
 fdoc is built to work around controller specs in rspec, and provides `Fdoc::SpecWatcher` as a mixin. Make sure to include it *inside* your top level describe.
 
-    require 'fdoc/spec_watcher'
+```ruby
+require 'fdoc/spec_watcher'
 
-    describe MembersController do
-      include Fdoc::SpecWatcher
-      ...
-    end
+describe MembersController do
+  include Fdoc::SpecWatcher
+  # ...
+end
+```
 
 To enable fdoc for an endpoint, add the `fdoc` option with the path to the endpoint. fdoc will intercept all calls to `get`, `post`, `put`, and `delete` and verify those parameters accordingly.
 
-    context "#show", :fdoc => 'members/list' do
-      ..
-    end
+```ruby
+context "#show", :fdoc => 'members/list' do
+  # ...
+end
+```
 
 fdoc also has a scaffolding mode, where it attemps to infer the schema of a request based on sample responses. The interface is exactly the same as verifying, just set the environment variable `FDOC_SCAFFOLD=true`.
 
@@ -51,7 +57,7 @@ fdoc provides the `fdoc_to_html` script to transform a directory of `.fdoc` file
 
 In this repo, try running:
 
-    bin/fdoc_to_html spec/fixtures html
+    bin/fdoc_to_html ./spec/fixtures ./html
 
 ## Example
 
@@ -60,37 +66,90 @@ In this repo, try running:
 - For more information on fdoc file naming conventions, please see the [fdoc file conventions guide][github_files].
 - For more information on how fdoc uses JSON schema, please see the [json schema usage document][github_json].
 
-Here is `members/list-POST.fdoc`:
-
-    description: The list of members.
-    requestParameters:
-      properties:
-        limit:
-          type: integer
-          required: no
-          default: 50
-          description: Limits the number of results returned, used for paging.
-    responseParameters:
-      properties:
-        members:
-          type: array
-          items:
-            title: member
-            description: Representation of a member
-            type: object
-            properties:
-              name:
-                description: Member's name
-                type: string
-                required: yes
-                example: Captain Smellypants
-    responseCodes:
-    - status: 200 OK
-      successful: yes
-      description: A list of current members
-    - status: 400 Bad Request
-      successful: no
-      description: Indicates malformed parameters
+Here is `docs/fdoc/members/list-GET.fdoc`:
+
+```yaml
+description: The list of members.
+requestParameters:
+  properties:
+    limit:
+      type: integer
+      required: no
+      default: 50
+      description: Limits the number of results returned, used for paging.
+responseParameters:
+  properties:
+    members:
+      type: array
+      items:
+        title: member
+        description: Representation of a member
+        type: object
+        properties:
+          name:
+            description: Member's name
+            type: string
+            required: yes
+            example: Captain Smellypants
+responseCodes:
+- status: 200 OK
+  successful: yes
+  description: A list of current members
+- status: 400 Bad Request
+  successful: no
+  description: Indicates malformed parameters
+```
+
+If we run a test against our members controller with an undocumented parameter, `offset`, we'll get an error.
+
+Our spec file, `spec/controllers/members_controller_spec.rb` looks like:
+
+```ruby
+require 'fdoc/spec_watcher'
+
+describe MembersController do
+  content "#show", :fdoc => "members/list" do
+    it "can take an offset" do
+      get :show, {
+        :offset => 5
+      }
+    end
+  end
+end
+```
+
+We run:
+
+    bundle exec rspec spec/controllers/members_controller_spec.rb
+
+And since `offset` is undocumented, fdoc will fail the test:
+
+    Failures:
+
+      1) MembersController#show can take an offset
+         Failure/Error: get :show, { :offset => 5 }
+         JSON::Schema::ValidationError:
+           The property '#/' contains additional properties ["offset"] outside of the schema when none are allowed in schema 8fcac6c4-294b-56a2-a3de-9342e2e729da#
+         # ./spec/controllers/members_controller_spec.rb:5:in `block (3 levels) in <top (required)>'
+
+If we run the same spec in scaffold mode, it passes and fdoc will write changes to the correspoding `.fdoc` file:
+
+    FDOC_SCAFFOLD=true bundle exec spec/controllers/members_controller_spec.rb
+
+The diff looks like:
+
+```diff
+diff --git a/docs/fdoc/members/list-GET.fdoc b/docs/fdoc/members/list-GET.fdoc b2e3656..dfa363a 100644
+--- a/docs/fdoc/members/list-GET.fdoc
++++ b/docs/fdoc/members/list-GET.fdoc
++    offset:
++      description: ???
++      required: ???
++      type: integer
++      example: 5
+```
+
+Notice how it infers a type, and copies an example, but leaves description and required blank. These fields are best left to humans to decide.
 
 
 ## Goals

data/lib/fdoc/presenters/html_presenter.rb

@@ -55,4 +55,15 @@ class Fdoc::HtmlPresenter
       html_path
     end
   end
+
+  def tag_with_anchor(tag, content, anchor_slug = nil)
+    anchor_slug ||= content.downcase.gsub(' ', '_')
+    <<-EOS
+    <#{tag} id="#{anchor_slug}">
+      <a href="##{anchor_slug}" class="anchor">
+        #{content}
+      </a>
+    </#{tag}>
+    EOS
+  end
 end

data/lib/fdoc/presenters/meta_service_presenter.rb

@@ -61,5 +61,6 @@ class Fdoc::MetaServicePresenter < Fdoc::HtmlPresenter
     presenter = Fdoc::EndpointPresenter.new(endpoint,
       options.merge(:prefix => (service_presenter.slug_name + "/")))
     presenter.service_presenter = service_presenter
+    presenter
   end
 end

data/lib/fdoc/presenters/schema_presenter.rb

@@ -128,11 +128,19 @@ class Fdoc::SchemaPresenter < Fdoc::HtmlPresenter
     properties.each do |key, property|
       next if property.nil?
       html << '<li>'
-      html << '<tt>%s</tt>' % key
+      html << tag_with_anchor(
+        'span',
+        '<tt>%s</tt>' % key,
+        schema_slug(key, property)
+      )
       html << self.class.new(property, options.merge(:nested => true)).to_html
       html << '</li>'
     end
 
     html
   end
+
+  def schema_slug(key, property)
+    "#{key}-#{property.hash}"
+  end
 end

data/lib/fdoc/templates/endpoint.html.erb

@@ -28,27 +28,27 @@
         <%= description %>
 
         <% if show_request? %>
-          <h2>Request</h2>
+          <%= tag_with_anchor('h2', 'Request') %>
 
-          <h3>Example Request</h3>
+          <%= tag_with_anchor('h3', 'Example Request') %>
           <%= example_request %>
 
-          <h3>Request Parameters</h3>
+          <%= tag_with_anchor('h3', 'Request Parameters') %>
           <%= request_parameters %>
         <% end %>
 
-        <h2>Response</h2>
+        <%= tag_with_anchor('h2', 'Response') %>
         <% if show_response? %>
-          <h3>Example Response</h3>
+          <%= tag_with_anchor('h3', 'Example Response') %>
           <%= example_response %>
 
-          <h3>Response Parameters</h3>
+          <%= tag_with_anchor('h3', 'Response Parameters') %>
           <%= response_parameters %>
         <% end %>
 
-        <h3>Response Codes</h3>
+        <%= tag_with_anchor('h3', 'Response Codes') %>
         <% if !successful_response_codes.empty? %>
-          <h4>Successful Response Codes</h4>
+          <%= tag_with_anchor('h4', 'Successful Response Codes') %>
           <ul>
             <% successful_response_codes.each do |response_code| %>
             <li>
@@ -59,7 +59,7 @@
         <% end %>
 
         <% if !successful_response_codes.empty? %>
-          <h4>Failure Response Codes</h4>
+          <%= tag_with_anchor('h4', 'Failure Response Codes') %>
           <ul>
             <% failure_response_codes.each do |response_code| %>
             <li>

data/lib/fdoc/templates/meta_service.html.erb

@@ -16,9 +16,7 @@
 
         <%= description %>
 
-        <h2>
-          Services
-        </h2>
+        <%= tag_with_anchor('h2', 'Services') %>
 
         <ul>
           <% services.each do |serv| %>
@@ -30,14 +28,10 @@
           <% end %>
         </ul>
 
-        <h2>
-          Endpoints
-        </h2>
+        <%= tag_with_anchor('h2', 'Endpoints') %>
 
         <% endpoints.each do |endpoint_ary| %>
-          <h3>
-            <%= endpoint_ary.first.prefix %>
-          </h3>
+          <%= tag_with_anchor('h3', endpoint_ary.first.prefix) %>
           <ul>
           <% endpoint_ary.each do |endpoint| %>
             <li>
@@ -48,9 +42,7 @@
         <% end %>
 
         <% if discussion %>
-          <h2>
-            Discussion
-          </h2>
+          <%= tag_with_anchor('h2', 'Discussion') %>
           <%= discussion %>
         <% end %>
       </div>

data/lib/fdoc/templates/service.html.erb

@@ -24,14 +24,10 @@
 
         <%= description %>
 
-        <h2>
-          Endpoints
-        </h2>
+        <%= tag_with_anchor('h2', 'Endpoints') %>
 
         <% endpoints.each do |endpoint_ary| %>
-          <h3>
-            <%= endpoint_ary.first.prefix %>
-          </h3>
+          <%= tag_with_anchor('h3', endpoint_ary.first.prefix) %>
           <ul>
           <% endpoint_ary.each do |endpoint| %>
             <li>
@@ -42,9 +38,7 @@
         <% end %>
 
         <% if discussion %>
-          <h2>
-            Discussion
-          </h2>
+          <%= tag_with_anchor('h2', 'Discussion') %>
           <%= discussion %>
         <% end %>
       </div>

data/lib/fdoc/templates/styles.css

@@ -29,6 +29,18 @@ h1, h2, h3 { font-weight: 200; }
 a { text-decoration: none; color: #66f; }
 a:hover, a:active { text-decoration: underline; }
 
+a.anchor { color: inherit; }
+a.anchor:hover, a.anchor:active { text-decoration: none;}
+a.anchor:hover::before, a.anchor.active::before {
+  background: white;
+  display: inline-block;
+  position: absolute;
+  content: '\0261E';
+  font-size: 120%;
+  font-weight: bold;
+  margin-left: -1.2em;
+}
+
 ul {
   list-style: square;
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fdoc
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -15,7 +15,7 @@ date: 2011-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70339438797600 !ruby/object:Gem::Requirement
+  requirement: &70290789895620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70339438797600
+  version_requirements: *70290789895620
 - !ruby/object:Gem::Dependency
   name: json-schema
-  requirement: &70339438796920 !ruby/object:Gem::Requirement
+  requirement: &70290789911300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: 1.0.1
   type: :runtime
   prerelease: false
-  version_requirements: *70339438796920
+  version_requirements: *70290789911300
 - !ruby/object:Gem::Dependency
   name: kramdown
-  requirement: &70339438796340 !ruby/object:Gem::Requirement
+  requirement: &70290789910780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70339438796340
+  version_requirements: *70290789910780
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70339438792260 !ruby/object:Gem::Requirement
+  requirement: &70290789910100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70339438792260
+  version_requirements: *70290789910100
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70339438791760 !ruby/object:Gem::Requirement
+  requirement: &70290789909420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -67,10 +67,10 @@ dependencies:
         version: '2.5'
   type: :development
   prerelease: false
-  version_requirements: *70339438791760
+  version_requirements: *70290789909420
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70339438791300 !ruby/object:Gem::Requirement
+  requirement: &70290789908980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -78,10 +78,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70339438791300
+  version_requirements: *70290789908980
 - !ruby/object:Gem::Dependency
   name: cane
-  requirement: &70339438790760 !ruby/object:Gem::Requirement
+  requirement: &70290789908380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -89,7 +89,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70339438790760
+  version_requirements: *70290789908380
 description: A tool for documenting API endpoints.
 email: support@squareup.com
 executables:
@@ -172,3 +172,4 @@ test_files:
 - spec/fixtures/members/members.fdoc.service
 - spec/fixtures/sample_group.fdoc.meta
 - spec/spec_helper.rb
+has_rdoc: