Skip to content

Instantly share code, notes, and snippets.

@bf4

bf4/autodoc_config.diff

Created May 2, 2016 06:15
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save bf4/5cab07d50711e482725f147f09bdb769 to your computer and use it in GitHub Desktop.
Save bf4/5cab07d50711e482725f147f09bdb769 to your computer and use it in GitHub Desktop.
Download ZIP
https://github.com/r7kamura/autodoc is so easy to use to generate API docs. Just add metadata to install, remove to uninstall. Customize templates and headers. Win!
Raw
autodoc_config.diff
diff --git a/Gemfile b/Gemfile
index f34a069..cb26600 100644
--- a/Gemfile
+++ b/Gemfile
@@ -100,6 +100,8 @@ group :test do
gem 'rspec', '~> 3.3'
gem 'rspec_junit_formatter', '~> 0.2' # per https://circleci.com/docs/test-metadata#automatic-test-metadata-collection
gem 'rspec-rails', group: :development
+ gem 'autodoc', require: false
+ gem 'redcarpet', require: false
diff --git a/Gemfile.lock b/Gemfile.lock
index d615bcb..62b8df4 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -124,6 +124,10 @@ GEM
+ autodoc (0.6.0)
+ actionpack
+ activesupport (>= 3.0.0)
+ rspec
@@ -433,6 +437,7 @@ GEM
+ redcarpet (3.3.3)
@@ -584,6 +589,7 @@ DEPENDENCIES
+ autodoc
@@ -652,6 +658,7 @@ DEPENDENCIES
rails (~> 4.2.0)
+ redcarpet
diff --git a/spec/support/autodoc.rb b/spec/support/autodoc.rb
new file mode 100644
index 0000000..faba50c
--- /dev/null
+++ b/spec/support/autodoc.rb
@@ -0,0 +1,35 @@
+# Usage:
+# AUTODOC=1 rspec
+ci = ENV['CI'] == 'true'
+if ci || ENV['AUTODOC'] == '1'
+
+ require 'autodoc'
+ require 'autodoc/rspec'
+ require 'redcarpet'
+ Autodoc.configuration.tap do |c|
+ if ci
+ c.path = 'reports/api'
+ else
+ c.path = "docs/api"
+ end
+ c.toc = true
+ c.toc_html = true
+ suppressed_headers = %w(Connection Content-Length Host Cache-Control ETag
+ Set-Cookie X-Content-Type-Options X-Frame-Options X-Request-Id X-Runtime X-XSS-Protection)
+ suppressed_headers << 'CONTENT_TYPE' # until https://github.com/rails-api/active_model_serializers/pull/1712 is merged
+ c.suppressed_request_header.concat suppressed_headers
+ c.suppressed_response_header.concat suppressed_headers
+ c.template = Rails.root.join('spec/support/autodoc/document.md.erb').read
+ c.toc_template = Rails.root.join('spec/support/autodoc/toc.md.erb').read
+ c.toc_html = Rails.root.join('spec/support/autodoc/document.md.erb').read
+ c.document_path_from_example = -> (example) do
+ example.file_path.gsub(%r{\./spec/requests/api/(.+)_(?:spec|shared)\.rb}, '\1.md')
+ end
+ end
+ RSpec.configure do |config|
+ config.before type: :request do
+ next if RSpec.current_example.file_path !~ %r{\./spec/requests/api/}
+ RSpec.current_example.metadata[:autodoc] = true
+ end
+ end
+end
diff --git a/spec/support/autodoc/document.md.erb b/spec/support/autodoc/document.md.erb
new file mode 100644
index 0000000..dc67304
--- /dev/null
+++ b/spec/support/autodoc/document.md.erb
@@ -0,0 +1,17 @@
+<%# coding: UTF-8 -%>
+## <%= title %>
+<%= description %>
+<%= parameters_section %>
+### Example
+
+#### Request
+```
+<%= method %> <%= request.path %><%= request_query %> <%= request_http_version %>
+<%= request_header %><%= request_body_section %>
+```
+
+#### Response
+```
+<%= response_http_version %> <%= response.status %>
+<%= response_header %><%= response_body_section %>
+```
\ No newline at end of file
diff --git a/spec/support/autodoc/toc.html.erb b/spec/support/autodoc/toc.html.erb
new file mode 100644
index 0000000..9fe3b8f
--- /dev/null
+++ b/spec/support/autodoc/toc.html.erb
@@ -0,0 +1,82 @@
+<%# coding: UTF-8 -%>
+<head>
+ <style>
+ .api-docs {
+ left: 210px;
+ }
+
+ .api-docs, .api-docs-toc {
+ width: 66%;
+ }
+
+ .api-action {
+ padding: 10px;
+ }
+
+ .tocify-wrapper {
+ overflow-y: auto;
+ overflow-x: hidden;
+ position: fixed;
+ width: 210px;
+ float: left;
+ font-size: 16px;
+ background-color: #AAAADD;
+ top: 1px;
+ bottom: -1px;
+ padding: 10px;
+ }
+
+ .generated-at {
+ position: fixed;
+ bottom: 10px;
+ }
+
+ .api-resource {
+ border-bottom: black 1px solid;
+ }
+
+ pre {
+ padding: 10px;
+ background-color: #CCCCEE;
+ }
+
+ .page-wrapper {
+ margin-left: 240px;
+ min-width: 700px;
+ position: relative;
+ z-index: 10;
+ }
+ </style>
+</head>
+<% markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, {fenced_code_blocks: true}) %>
+<% document_markdown = '' %>
+<html>
+<div class='tocify-wrapper'>
+<h1> Table of Contents </h1>
+<% @table.sort.each do |pathname, documents| -%>
+ <% title = pathname.cleanpath.to_s.sub(/^.*doc\//,'') -%>
+ <% link = pathname.to_s.html_safe -%>
+ <li>
+ <a href="#<%= link -%>"><%= title -%></a>
+ </li>
+ <%
+ document_markdown += '<div id="' + pathname.to_s.html_safe + '" class="api-resource">'
+ documents.each do |document|
+ document_markdown += '<div class="api-action">'
+ document_markdown += markdown.render(document.render)
+ document_markdown += '</div>'
+ end
+ document_markdown += '</div>'
+ %>
+<% end -%>
+<div class='generated-at'>
+Generated at:
+<br>
+<%= Time.now.to_s -%>
+</div>
+</div>
+
+<div class='page-wrapper'>
+ <%= document_markdown -%>
+</div>
+</html>
\ No newline at end of file
diff --git a/spec/support/autodoc/toc.md.erb b/spec/support/autodoc/toc.md.erb
new file mode 100644
index 0000000..35cbe97
--- /dev/null
+++ b/spec/support/autodoc/toc.md.erb
@@ -0,0 +1,12 @@
+<%# coding: UTF-8 -%>
+## Table of Contents
+<% @table.sort.each do |pathname, documents| -%>
+<% relative_path = pathname.relative_path_from(Autodoc.configuration.pathname) -%>
+* [<%= relative_path %>](<%= relative_path %>)
+<% documents.group_by(&:title).each do |title, documents| -%>
+<% documents.each_with_index do |document, index| -%>
+<% suffix = index == 0 ? "" : "-#{index}" -%>
+ * [<%= title %>](<%= "#{relative_path}##{document.identifier}#{suffix}" %>)
+<% end -%>
+<% end -%>
+<% end -%>
\ No newline at end of file
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment