yard-api 0.3.7 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3af67e45e3ab8fd41ef0ec5cb1578e1978361579796e4d2720f9a09907ded38
-  data.tar.gz: 488360b56b9a807e8e6a8671b3aeae13b83f3400d01cf6f826b0cbdf9881337b
+  metadata.gz: a0208f3a8c85cce1ea72f163295779b101976a8b35cdef210e23dc6b3997577b
+  data.tar.gz: cb55240abab2888e59c9929a56cf9c29f1cd70cbe038d4ec13f616a61e3b9b63
 SHA512:
-  metadata.gz: b1dfd66a16c6e4a1d76a121b2fc74ab9cd813e1336bb51ef36b6c54d9baea7e39fff89cb125759f784cb18d629259d340e655010a32f4709b85e43f92529f936
-  data.tar.gz: 85b89092da99271aad2c5b09b77ee32d5b1b93e25493ed16682263bed6cd3175c24c8ff21a4d3507fad9e3a5414b09079bae5c4bb095c3db4c0675a5a27bffdb
+  metadata.gz: 2aa7523f95c559e211d4c5bb812d1314c18f22b6712bb706df9cde72b8cb53eb5d3a8d00f626708cef43e283f5e2fc9dc0838055a9420f8843a8d064f4c74cc7
+  data.tar.gz: d9d12b708e52097531be4ba50ed4f5e8ab65b6eb4362f07b81a1da0253f4d6324d76114978efbaa4d9c0b425b6226709c156fdcbf74edbfc68eaa5227ee2e55e

data/README.md

@@ -40,65 +40,7 @@ Read that file to view all the available options.
 
 ## Changelog
 
-**6/9/2015 [0.3.5]**
-
-- In JSON format, an API resource endpoint now contains the name as well.
-- Changed the `topicize()` helper in a way that makes the IDs (and URLs of
-  some sections) much more readable
-
-**23/8/2015 [0.3.4]**
-
-- Fixed an issue that prevented overriding the Rake task's options at runtime.
-- Updated `config/yard_api.yml` to reflect the recently added options.
-
-**17/8/2015 [0.3.3]**
-
-- Improved the JSON format's output to be more concise and consistent.
-
-**30/7/2015 [0.3.1]**
-
-- Fixed a bug that was listing all the endpoints of a certain controller even if they do not have a route defined. Now, YARD-API will warn about endpoints that have an `@API` tag but could not be routed.
-- Greatly improved the performance of generating the Quicklinks table.
-
-**29/7/2015 [0.3.0]**
-
-- major rework of the linking logic, much improvements but some stuff is broken now
-
-**28/7/2015 [0.2.3]**
-
-- dropped the `@argument_scope` tag
-- JSON is available as an output format now
-- added usage documentation, found at [http://amireh.github.io/yard-api]
-- added an example app
-- various style improvements
-- `@example_request` is now able to output a sample cURL command.
-
-**0.1.7**
-
-- new compatibility option `leading_argument_name_fix`
-
-**15/9/2014**
-
-- `@argument` tags can now be formatted in a table by setting the `tabular_arguments` option to true
-- `@argument_scope`: a new tag that improves the formatting of endpoint arguments that are scoped by a common prefix (e.g, nested inside a json object), like `user[name]` => `name`
-- `@argument` can now parse accepted values in two formats; inline within the types array, or by explicitly writing it in the tag text using any of `Accepted values: [...]`, `Accepts: [...]`, or `Possible values: [...]`
-- A new option: `strict_arguments` that provides a default for the `is_required` property of `@argument` tags. This default is used if the tag does not explicitly state `Optional` or `Required` in its type specifier.
-- Support for dynamic javascript and style code based on options. See `templates/layout/setup.rb#inline_{javascripts,stylesheets}`
-- A new set of options for customizing layout: `content_width`, `sidebar_width` and `spacer`
-- `github_url` and `github_branch` options for tuning api endpoint source links
-
-**14/9/2014**
-
-- Support for single-page output through the `one_file` option
-- Support for resource index generation ("All Resources") through the `resource_index` option
-
-**10/9/2014**
-
-- Support for github-flavored markdown when you're using Markdown as a markup, and `redcarpet` as the provider
-- Syntax highlighting for multiple languages (with auto-detection) using [highlight.js](https://highlightjs.org/)
-- `@example_response` and `@example_request` tags now support a title for the response
-- A new option: `copyright` for displaying a copyright in the footer of every page
-- A new option: `footer_note` for displaying a custom note, like linking to the project's source code, in the footer of every page
+See CHANGES.md.
 
 ## License
 

data/lib/yard-api/markup/redcarpet.rb

@@ -17,7 +17,7 @@ module YARD::APIPlugin::Markup
     }.freeze
 
     RendererOptions = {
-    }.freeze
+    }
 
     def initialize(text, extensions_and_options=nil)
       @renderer = Redcarpet::Render::HTML.new(RendererOptions)

data/lib/yard-api/options.rb

@@ -21,6 +21,7 @@ module YARD::APIPlugin
     default_attr :footer_note, ''
 
     default_attr :one_file, false
+    default_attr :include_internal, false
     default_attr :strict, false
     default_attr :verbose, ENV['VERBOSE'] || false
     default_attr :debug, ENV['DEBUG'] || false

data/lib/yard-api/templates/helpers/html_helper.rb

@@ -100,7 +100,7 @@ module YARD::Templates::Helpers::HtmlHelper
     end
   end
 
-  def sidebar_link(href, title, is_active)
+  def sidebar_link(href, title, is_active=false)
     link_url(href, title, { class: is_active ? 'active' : '' })
   end
 

data/lib/yard-api/templates/helpers/route_helper.rb

@@ -31,8 +31,17 @@ module YARD::Templates::Helpers
       end
 
       def get_route_verb(route)
-        route.verb.source =~ /\^?(\w*)\$/ ? $1.upcase : route.verb.source
+        verb = route.verb
+
+        case verb
+        when Regexp
+          verb.source =~ /\^?(\w*)\$/ ? $1.upcase : verb.source
+        when String
+          verb
+        else
+          "???"
+        end
       end
     end
   end
-end
+end

data/lib/yard-api/verifier.rb

@@ -22,13 +22,14 @@ module YARD
       end
 
       def relevant_object?(object)
+        doc_include_internal = !!YARD::APIPlugin.options[:include_internal]
         case object.type
         when :root, :module, :constant
           false
         when :api
           true
         when :method
-          return false if object.has_tag?(:internal) || !object.has_tag?(:API)
+          return false if object.has_tag?(:internal) && !doc_include_internal || !object.has_tag?(:API)
           routes = @routes[object.object_id]
           routes ||= begin
             @routes[object.object_id] = YARD::Templates::Helpers::RouteHelper.routes_for_yard_object(object)
@@ -43,7 +44,7 @@ module YARD
 
           routes.any?
         when :class
-          return false if object.has_tag?(:internal) || !object.has_tag?(:API)
+          return false if object.has_tag?(:internal) && !doc_include_internal || !object.has_tag?(:API)
           true
         else
           object.parent.nil? && relevant_object?(object.parent)

data/lib/yard-api/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module APIPlugin
-    VERSION = "0.3.7"
+    VERSION = "1.1.2"
   end
 end

data/spec/fulldoc_spec.rb

@@ -1,25 +1,5 @@
 require 'spec_helper'
 
-module YARD
-  module Serializers
-    # A serializer that writes data to standard output.
-    class SpecSerializer < Base
-      # Creates a serializer to print text to stdout
-      #
-      # @param [Fixnum, nil] wrap if wrap is a number, wraps text to +wrap+
-      #   columns, otherwise no wrapping is done.
-      def initialize(buffer)
-        @buffer = buffer
-      end
-
-      # Overrides serialize behaviour to write data to standard output
-      def serialize(object, data)
-        @buffer << data
-      end
-    end
-  end
-end
-
 describe YARD::Templates::Engine.template(:api, :fulldoc) do
   before do
     Registry.clear

data/spec/spec_helper.rb

@@ -1,3 +1,6 @@
+require 'json'
+require 'pry'
+
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
 # The generated `.rspec` file contains `--require spec_helper` which will cause this
@@ -15,7 +18,6 @@
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
-
   require File.join(File.dirname(__FILE__), '..', 'lib', 'yard-api')
 
   # rspec-expectations config goes here. You can use an alternate
@@ -123,3 +125,26 @@ RSpec.configure do |config|
     YARD.parse_string str if str
   end
 end
+
+
+module YARD
+  module Serializers
+    # A serializer that writes data to standard output.
+    class SpecSerializer < Base
+      attr_writer :basepath
+
+      # Creates a serializer to print text to stdout
+      #
+      # @param [Fixnum, nil] wrap if wrap is a number, wraps text to +wrap+
+      #   columns, otherwise no wrapping is done.
+      def initialize(buffer)
+        @buffer = buffer
+      end
+
+      # Overrides serialize behaviour to write data to standard output
+      def serialize(object, data)
+        @buffer << data
+      end
+    end
+  end
+end

data/spec/tags/internal_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+describe YARD::Templates::Engine.template(:api, :fulldoc) do
+  before(:each) do
+    YARD::Registry.clear
+  end
+
+  after(:each) do
+    YARD::Registry.clear
+  end
+
+  before(:each) do
+    populate <<-'eof'
+      # @API Quizzes
+      # @internal
+      class QuizzesController < ApplicationController
+      end
+    eof
+  end
+
+  let(:serializer) { YARD::Serializers::SpecSerializer.new([]) }
+  let(:verifier) { YARD::APIPlugin::Verifier.new }
+
+  it 'should hide entities marked with @internal' do
+    entities = YARD::Registry.all
+
+    YARD::Templates::Engine.render({
+      objects: entities,
+      type: :fulldoc,
+      template: :api,
+      format: :json,
+      serializer: serializer
+    })
+
+    expect(entities.size).to be > 0
+    expect(verifier.run(entities).size).to be == 0
+  end
+
+  context 'when the "include_internal" option is turned on...' do
+    before(:each) do
+      set_option(:include_internal, true)
+    end
+
+    it 'should not hide entities marked with @internal' do
+      populate <<-'eof'
+        # @API Quizzes
+        # @internal
+        class QuizzesController < ApplicationController
+        end
+      eof
+
+      entities = YARD::Registry.all
+
+      YARD::Templates::Engine.render({
+        objects: entities,
+        type: :fulldoc,
+        template: :api,
+        format: :json,
+        serializer: serializer
+      })
+
+      expect(entities.size).to be > 0
+      expect(verifier.run(entities).size).to eq(entities.size)
+    end
+  end
+end

data/templates/api/fulldoc/html/css/highlight.css

@@ -0,0 +1,153 @@
+/*
+
+Original style from softwaremaniacs.org (c) Ivan Sagalaev <Maniac@SoftwareManiacs.Org>
+
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 0.5em;
+  background: #f0f0f0;
+  -webkit-text-size-adjust: none;
+}
+
+.hljs,
+.hljs-subst,
+.hljs-tag .hljs-title,
+.nginx .hljs-title {
+  color: black;
+}
+
+.hljs-string,
+.hljs-title,
+.hljs-constant,
+.hljs-parent,
+.hljs-tag .hljs-value,
+.hljs-rules .hljs-value,
+.hljs-preprocessor,
+.hljs-pragma,
+.haml .hljs-symbol,
+.ruby .hljs-symbol,
+.ruby .hljs-symbol .hljs-string,
+.hljs-template_tag,
+.django .hljs-variable,
+.smalltalk .hljs-class,
+.hljs-addition,
+.hljs-flow,
+.hljs-stream,
+.bash .hljs-variable,
+.apache .hljs-tag,
+.apache .hljs-cbracket,
+.tex .hljs-command,
+.tex .hljs-special,
+.erlang_repl .hljs-function_or_atom,
+.asciidoc .hljs-header,
+.markdown .hljs-header,
+.coffeescript .hljs-attribute {
+  color: #800;
+}
+
+.smartquote,
+.hljs-comment,
+.hljs-annotation,
+.hljs-template_comment,
+.diff .hljs-header,
+.hljs-chunk,
+.asciidoc .hljs-blockquote,
+.markdown .hljs-blockquote {
+  color: #888;
+}
+
+.hljs-number,
+.hljs-date,
+.hljs-regexp,
+.hljs-literal,
+.hljs-hexcolor,
+.smalltalk .hljs-symbol,
+.smalltalk .hljs-char,
+.go .hljs-constant,
+.hljs-change,
+.lasso .hljs-variable,
+.makefile .hljs-variable,
+.asciidoc .hljs-bullet,
+.markdown .hljs-bullet,
+.asciidoc .hljs-link_url,
+.markdown .hljs-link_url {
+  color: #080;
+}
+
+.hljs-label,
+.hljs-javadoc,
+.ruby .hljs-string,
+.hljs-decorator,
+.hljs-filter .hljs-argument,
+.hljs-localvars,
+.hljs-array,
+.hljs-attr_selector,
+.hljs-important,
+.hljs-pseudo,
+.hljs-pi,
+.haml .hljs-bullet,
+.hljs-doctype,
+.hljs-deletion,
+.hljs-envvar,
+.hljs-shebang,
+.apache .hljs-sqbracket,
+.nginx .hljs-built_in,
+.tex .hljs-formula,
+.erlang_repl .hljs-reserved,
+.hljs-prompt,
+.asciidoc .hljs-link_label,
+.markdown .hljs-link_label,
+.vhdl .hljs-attribute,
+.clojure .hljs-attribute,
+.asciidoc .hljs-attribute,
+.lasso .hljs-attribute,
+.coffeescript .hljs-property,
+.hljs-phony {
+  color: #88f;
+}
+
+.hljs-keyword,
+.hljs-id,
+.hljs-title,
+.hljs-built_in,
+.css .hljs-tag,
+.hljs-javadoctag,
+.hljs-phpdoc,
+.hljs-dartdoc,
+.hljs-yardoctag,
+.smalltalk .hljs-class,
+.hljs-winutils,
+.bash .hljs-variable,
+.apache .hljs-tag,
+.hljs-type,
+.hljs-typename,
+.tex .hljs-command,
+.asciidoc .hljs-strong,
+.markdown .hljs-strong,
+.hljs-request,
+.hljs-status {
+  font-weight: bold;
+}
+
+.asciidoc .hljs-emphasis,
+.markdown .hljs-emphasis {
+  font-style: italic;
+}
+
+.nginx .hljs-built_in {
+  font-weight: normal;
+}
+
+.coffeescript .javascript,
+.javascript .xml,
+.lasso .markup,
+.tex .hljs-formula,
+.xml .javascript,
+.xml .vbscript,
+.xml .css,
+.xml .hljs-cdata {
+  opacity: 0.5;
+}

data/templates/api/fulldoc/json/setup.rb

@@ -55,7 +55,22 @@ def dump_object(obj)
     is_required = prop.has_key?('required') ? prop['required'] : false
     is_required_str = is_required ? 'Required' : 'Optional'
 
-    ArgumentTag.new(nil, "[#{is_required_str}, #{prop['type']}] #{prop_name}\n #{prop['description']}")
+    {
+      "name" => prop_name,
+      "types" => Array(prop["type"]),
+      "is_required" => !!prop["required"],
+      "text" => prop.fetch('description', ''),
+      "example" => prop['example'],
+      "accepted_values" => Array(
+        first_in([
+          "accepted values",
+          "accepted_values",
+          "accepts",
+          "accepted",
+          "acceptable values",
+        ], prop)
+      )
+    }
   end
 
   {
@@ -64,7 +79,7 @@ def dump_object(obj)
     title: title,
     text: spec['description'] || '',
     controller: obj.object.path,
-    schema: schema_tags.as_json.map { |e| e.delete('tag_name'); e }
+    schema: schema_tags
   }
 end
 
@@ -114,15 +129,13 @@ def get_route(object)
   route = routes.first
 
   if route.present?
-    verb = if route.verb.source =~ /\^?(\w*)\$/
-      $1.upcase
-    else
-      route.verb.source
-    end
-
     {
-      path: route.path.spec.to_s.gsub("(.:format)", ""),
-      verb: verb
+      path: RouteHelper.get_route_path(route),
+      verb: RouteHelper.get_route_verb(route)
     }
   end
 end
+
+def first_in(keys, obj)
+  obj[keys.detect { |k| obj.key?(k) }]
+end

data/yard-api.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
                   ['LICENSE', 'README.md', '.rspec', __FILE__]
   s.has_rdoc    = 'yard'
   s.license     = 'AGPL-3.0'
-  s.add_dependency 'yard', '0.8.7'
+  s.add_dependency 'yard', '~> 0.9.15'
   s.add_dependency 'yard-appendix', '~> 0.1.8'
   s.add_development_dependency 'rspec', '~> 3.3'
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: yard-api
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 1.1.2
 platform: ruby
 authors:
 - Ahmad Amireh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-25 00:00:00.000000000 Z
+date: 2020-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.7
+        version: 0.9.15
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.7
+        version: 0.9.15
 - !ruby/object:Gem::Dependency
   name: yard-appendix
   requirement: !ruby/object:Gem::Requirement
@@ -82,6 +82,7 @@ files:
 - spec/helpers/html_helper_spec.rb
 - spec/spec_helper.rb
 - spec/tags/argument_spec.rb
+- spec/tags/internal_spec.rb
 - tasks/yard_api.rake
 - templates/api/appendix/html/setup.rb
 - templates/api/appendix/json/setup.rb
@@ -206,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.7.6.2
 signing_key: 
 specification_version: 4
 summary: A YARD plugin for documenting APIs in Rails projects.

data/templates/api/fulldoc/html/css/highlight.css

@@ -1 +0,0 @@
-templates/api/fulldoc/html/css/../js/highlight/styles/mono-blue.css