fern-documentation 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3491257137267e449dc4e108d412604532bafd24
+  data.tar.gz: e070df10cc6dcaca700bcf9693736d718f4d8bc5
+SHA512:
+  metadata.gz: cd10e17c74c1d98ddfac57ddbde87218ad24578c0b9435075f086241d57ff06b06af93d89da0eccf8d5c6d75202d763c46ca28da6f881b149f6d92a858832441
+  data.tar.gz: 9c5a3f95fe0c43a4f7c0f451be478a1716fded5f8e7dfea01136e080c18d284f2059db43095ff6a456d99ef2d4ace3554940653ad6ea328282425f867dee057e

data/lib/fern-documentation.rb

@@ -0,0 +1 @@
+require 'fern/documentation'

data/lib/fern/documentation.rb

@@ -0,0 +1,4 @@
+require 'fern/documentation/dsl'
+require 'fern/documentation/railtie' if defined?(Rails)
+
+ActiveSupport.on_load(:action_controller) { include Fern::Documentation }

data/lib/fern/documentation/dsl.rb

@@ -0,0 +1,20 @@
+require 'fern/api'
+
+module Fern
+  module Documentation
+    module Dsl
+      def self.included(receiver)
+        receiver.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      def doc(str)
+        @controller.fern[@name][:doc] = str
+      end
+    end
+  end
+end
+
+Fern::Api::Endpoint.class_eval { include Fern::Documentation::Dsl }

data/lib/fern/documentation/markdown_generator.rb

@@ -0,0 +1,94 @@
+require 'mustache'
+
+module Fern
+  module Documentation
+    class MarkdownGenerator
+      TEMPLATE = %(# {{verb}} {{path}}
+
+_{{controller}}\#{{action}}_
+
+{{doc}}
+
+{{#has_parameters}}
+## Parameters
+
+| Name | Type | Array | Required | Min | Max | Values | Default |
+| ---- | ---- | ----- | -------- | --- | --- | ------ | ------- |
+{{#parameters}}
+| {{name}} | `{{ type }}` | {{ array }} | {{ required }} | {{ min }} | {{ max }} | {{ values }} | {{ default }} |
+{{/parameters}}
+{{/has_parameters}}
+
+{{#has_form}}
+## Form
+
+{{#form}}
+### Class
+
+`{{klass}}`
+
+{{#key}}
+### Key
+
+`{{key}}`
+{{/key}}
+{{/form}}
+
+{{#presenter}}
+## Presenter
+
+### Class
+
+`{{presenter}}`
+{{/presenter}}
+{{/has_form}}).freeze
+
+      def initialize(analysis)
+        @analysis = analysis
+      end
+
+      def generate
+        params = build_params
+
+        Mustache.render(
+          TEMPLATE,
+          verb: @analysis[:verb],
+          path: @analysis[:path],
+          controller: @analysis[:controller],
+          action: @analysis[:action],
+          doc: @analysis[:doc],
+          has_parameters: params.present?,
+          parameters: params,
+          has_form: @analysis[:form].present?,
+          form: @analysis[:form],
+          presenter: @analysis[:presenter]
+        )
+      end
+
+      private
+
+      def build_params
+        return if @analysis[:params].nil?
+        @analysis[:params].map { |name, config| build_param(name, config) }
+      end
+
+      def build_param(name, config)
+        constraints = config[:constraints]
+        {
+          name: name,
+          type: config[:type],
+          array: check(constraints[:array]),
+          required: check(constraints[:required]),
+          min: constraints[:min],
+          max: constraints[:max],
+          values: constraints[:values]&.join(', '),
+          default: constraints[:default]
+        }
+      end
+
+      def check(val)
+        val ? '✓' : ''
+      end
+    end
+  end
+end

data/lib/fern/documentation/railtie.rb

@@ -0,0 +1,9 @@
+module Fern
+  module Documentation
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load 'tasks/docs.rake'
+      end
+    end
+  end
+end

data/lib/fern/documentation/route_analyzer.rb

@@ -0,0 +1,54 @@
+module Fern
+  module Documentation
+    class RouteAnalyzer
+      def initialize(route)
+        @route = route
+      end
+
+      def analyze
+      	return nil if path.nil?
+
+        puts "Analyzing #{path}"
+
+        {
+          verb: verb,
+          path: path,
+          controller_name: controller_name,
+          controller: controller,
+          action: action,
+          params: fern[:params],
+          doc: fern[:doc],
+          form: fern[:form],
+          presenter: fern[:presenter]
+        }
+      end
+
+      private
+
+      def action
+        @route.defaults[:action]
+      end
+
+      def controller
+        "#{controller_name.camelize}Controller".constantize
+      end
+
+      def controller_name
+        @route.defaults[:controller]
+      end
+
+      def fern
+        controller.fern[action.to_sym]
+      end
+
+      def path
+        match = /(^[^\(]+)\([^\)]+\)/.match(@route.path.spec.to_s)
+        match[1] if match
+      end
+
+      def verb
+        @route.verb
+      end
+    end
+  end
+end

data/lib/fern/documentation/version.rb

@@ -0,0 +1,5 @@
+module Fern
+  module Documentation
+    VERSION = '0.0.1'.freeze
+  end
+end

data/lib/tasks/docs.rake

@@ -0,0 +1,36 @@
+require 'fileutils'
+
+require 'fern/documentation/route_analyzer'
+require 'fern/documentation/markdown_generator'
+
+namespace :fern do
+  desc 'Generate documentation'
+  task docs: :environment do
+    endpoints = []
+
+    Rails.application.routes.routes.each do |route|
+      next if route.internal
+      analysis = Fern::Documentation::RouteAnalyzer.new(route).analyze
+
+      if analysis.nil?
+	    puts "Skipping route"
+      else
+      	endpoints << analysis
+      end
+    end
+
+    doc_root = Rails.root.join('docs', 'api')
+
+    FileUtils.rm_rf(doc_root)
+    FileUtils.mkdir_p(doc_root)
+
+    endpoints.each do |endpoint|
+      filename = "#{endpoint[:controller_name]}-#{endpoint[:action]}.md"
+      filepath = File.join(doc_root, filename)
+      filedir = File.dirname(filepath)
+      FileUtils.mkdir_p(filedir)
+      content = Fern::Documentation::MarkdownGenerator.new(endpoint).generate
+      File.write(filepath, content)
+    end
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: fern-documentation
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kyle Kestell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mustache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Automatically generate documentation for Fern APIs.
+email: kyle@kestell.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/fern-documentation.rb
+- lib/fern/documentation.rb
+- lib/fern/documentation/dsl.rb
+- lib/fern/documentation/markdown_generator.rb
+- lib/fern/documentation/railtie.rb
+- lib/fern/documentation/route_analyzer.rb
+- lib/fern/documentation/version.rb
+- lib/tasks/docs.rake
+homepage: https://github.com/fern-fb/fern-documentation
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Fern Documentation
+test_files: []