yard-rails_plugin 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ee5828356df79f9af3841f7af240528c7492e282006ea6aadd898e722e5fc51
+  data.tar.gz: 233988e9b1e65313f07e71f7883cd3a95e054f7b9eca51e108d16945d29ff62f
+SHA512:
+  metadata.gz: 5259b1ea921d2edf76559a0e35d1d984361db8ccca868200490bafd057d16e419b1f25df3baf663db311396cc4abeb26437343458ec51b7d17ac597353de7c51
+  data.tar.gz: 047d79b8493048018b46f92a40223d9a24734ec15331b38a83b7672b9a0d2bc634fa6396aff1adb24e075af5b5436f8d0adb3875de891ab5f1cc87c1e9ab5a2e

data/.github/workflows/gem-push.yml

@@ -0,0 +1,47 @@
+name: Ruby Gem
+
+on:
+  push:
+    branches: [ "release" ]
+  pull_request:
+    branches: [ "release" ]
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby 3.3
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.3.0
+
+    - name: Publish to GPR
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
+      env:
+        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+        OWNER: ${{ github.repository_owner }}
+
+    - name: Publish to RubyGems
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.github/workflows/ruby.yml

@@ -0,0 +1,37 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies, and run tests with Rake
+# For more information, see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.3']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+      uses: ruby/setup-ruby@v1 # v1.146.0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+/.yardoc/
+Gemfile.lock
+/_yardoc/
+/doc/
+/rdoc/
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+.rvmrc

data/.ruby-gemset

@@ -0,0 +1 @@
+yard-rails_plugin

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in yard-rails-plugin.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Meter-reader
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# Yard::Rails::Plugin
+
+This plugin for [Yard](http://yardoc.org) permits to generate the documentation about a [Rails](http://rubyonrails.org) project.
+
+This means to handle in the correct way things such **models**, **controllers**, **routes** and so on.
+
+At now this plugin manages:
+
+- Routes
+  - creates a summary file
+  - adds to each controller and action its routes
+- Controller Params
+  - adds to each action a list of params taken
+
+You are more than invited to contribute!
+
+## Installation
+
+For now this gem is available only through github so add this line to your application's Gemfile:
+
+```bash
+    gem 'yard-rails_plugin'
+```
+
+Execute:
+
+```bash
+    bundle
+```
+
+Then edit the file ```.yardopts``` with
+
+```ruby
+    "{lib,app}/**/*.rb" --plugin rails-plugin - tmp/routes.html
+```
+
+## Usage
+
+Now you can execure yard doc with
+
+```bash
+    bundle exec yard
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/test*.rb']
+  t.verbose = true
+end
+
+task default: :test

data/lib/yard-rails_plugin/controller_params_handler.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module YARD
+  module Rails
+    module Plugin
+      # Handles Rails controller parameters
+      class ControllerParamsHandler < YARD::Handlers::Ruby::Base
+        handles(/params\[(:|')\w+'?\]/)
+        def process
+          return unless owner.is_a?(YARD::CodeObjects::MethodObject)
+
+          op = owner.parent
+          return unless op.is_a?(YARD::CodeObjects::ClassObject) || op.name.to_s[/Controller/]
+
+          (owner[:params] ||= []) << statement.source.match(/params\[((:|')\w+'?)\]/)[1]
+        end
+      end
+    end
+  end
+end

data/lib/yard-rails_plugin/routes.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module YARD
+  module Rails
+    module Plugin
+      # Handles Rails's route documentations
+      class Routes
+        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/MethodLength
+        def initialize
+          puts '[rails-plugin] Analyzing Routes...'
+          @routes = load_routes.collect do |route|
+            next if route[:path] =~ '/rails/info/properties|^/assets'
+
+            reqs = route.requirements.dup
+
+            return { name: route.name.to_s,
+                     verb: route.verb.to_s,
+                     path: route.path.spec.to_s,
+                     action: reqs[:action],
+                     controller: get_controller(reqs),
+                     rack_app: get_rack_app(route),
+                     constraints: get_constraints(reqs) }
+          end
+        end
+
+        def generate_routes_description_file(filename)
+          template = %q(
+          <html>
+          <head></head>
+          <body>
+            <h1>Routes</h1>
+            <table>
+              <tr style='background: #EAF0FF; font-weight: bold; line-height: 28px; text-align: left'>
+                <th>Rails Method</th>
+                <th>Verb</th>
+                <th>Endpoint</th>
+                <th>Destination</th>
+              </tr>
+              <% i = 0;
+              @routes.each do |r|
+                odd_or_even = (i.even? ? 'even' : 'odd')
+                destination = if r[:rack_app]
+                  "<pre>#{r[:rack_app].inspect} #{r[:constraints]}</pre>"
+                else
+                  "{#{r[:controller]} #{r[:controller]}}##{r[:action]}  #{r[:constraints]}"
+                end
+                endpoint = r[:path].gsub(/(:|\*)\w+/) do |m|
+                  "<span style='font-family: monospace; color: green'>#{m}</span>"
+                end
+                i += 1
+              %>
+              <tr class='#{odd_or_even}'>
+                <td><%= r[:name]%></td>
+                <td><%= r[:verb]%></td>
+                <td><%= endpoint%></td>
+                <td><%= destination%></td>
+              </tr>"
+              <% end %>
+              </table>
+            </body>
+          </html>').gsub(/^  /, '')
+          erb = ERB.new(template, trim_mode: '%<>')
+
+          File.write(File.join(Dir.pwd, filename), erb.result)
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def enrich_controllers
+          @routes.each do |r|
+            next unless r[:controller]
+
+            node = YARD::Registry.resolve(nil, r[:controller], true)
+            (node[:routes] ||= []) << r
+
+            next unless r[:action]
+
+            node = YARD::Registry.resolve(nil, "#{r[:controller]}##{r[:action]}", true)
+            (node[:routes] ||= []) << r
+          end
+        end
+      end
+
+      private
+
+      def load_routes
+        ::Rails.application.reload_routes!
+        ::Rails.application.routes.routes
+      end
+
+      def get_controller(reqs)
+        return unless reqs[:controller]
+
+        "#{reqs[:controller].upcase.gsub('_', '').gsub('/', '::')}_Controller"
+      end
+
+      def get_constraints(reqs)
+        return unless reqs.except(:controller, :action).present?
+
+        reqs.except(:controller, :action).inspect
+      end
+
+      def get_rack_app(route)
+        return unless route.app.is_a?('ActionDispatch::Routing')
+
+        route.app.inspect
+      end
+    end
+  end
+end

data/lib/yard-rails_plugin/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module YARD
+  module Rails
+    module Plugin
+      VERSION = '0.0.3'
+    end
+  end
+end

data/lib/yard-rails_plugin.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'yard-rails_plugin/version'
+require 'yard-rails_plugin/routes'
+require 'yard-rails_plugin/controller_params_handler'
+
+YARD::Templates::Engine.register_template_path "#{File.dirname(__FILE__)}/../templates"
+
+# After Source Parsing
+def load_rails_environment(env)
+  puts "[rails-plugin] Loading Rails environment (#{env})..."
+  ENV['RAILS_ENV'] = env
+  require File.join(Dir.pwd, 'config/environment')
+end
+
+YARD::Parser::SourceParser.after_parse_list do
+  load_rails_environment 'development'
+  routes = YARD::Rails::Plugin::Routes.new
+  routes.generate_routes_description_file 'tmp/routes.html'
+  routes.enrich_controllers
+end

data/techstack.md

@@ -0,0 +1,47 @@
+<!--
+&lt;--- Readme.md Snippet without images Start ---&gt;
+## Tech Stack
+Meter-Reader/yard_rails_plugin is built on the following main stack:
+
+
+
+Full tech stack [here](/techstack.md)
+
+&lt;--- Readme.md Snippet without images End ---&gt;
+
+&lt;--- Readme.md Snippet with images Start ---&gt;
+## Tech Stack
+Meter-Reader/yard_rails_plugin is built on the following main stack:
+
+
+
+Full tech stack [here](/techstack.md)
+
+&lt;--- Readme.md Snippet with images End ---&gt;
+-->
+<div align="center">
+
+# Tech Stack File
+![](https://img.stackshare.io/repo.svg "repo") [Meter-Reader/yard_rails_plugin](https://github.com/Meter-Reader/yard_rails_plugin)![](https://img.stackshare.io/public_badge.svg "public")
+<br/><br/>
+|1<br/>Tools used|04/26/24 <br/>Report generated|
+|------|------|
+</div>
+
+## <img src='https://img.stackshare.io/devops.svg'/> DevOps (1)
+<table><tr>
+  <td align='center'>
+  <img width='36' height='36' src='https://img.stackshare.io/service/1046/git.png' alt='Git'>
+  <br>
+  <sub><a href="http://git-scm.com/">Git</a></sub>
+  <br>
+  <sub></sub>
+</td>
+
+</tr>
+</table>
+
+<br/>
+<div align='center'>
+
+Generated via [Stack File](https://github.com/marketplace/stack-file)

data/techstack.yml

@@ -0,0 +1,20 @@
+repo_name: Meter-Reader/yard_rails_plugin
+report_id: e9859831d9572fbeb9866f8a46387bd2
+version: 0.1
+repo_type: Public
+timestamp: '2024-04-26T13:35:54+00:00'
+requested_by: Antronin
+provider: github
+branch: main
+detected_tools_count: 1
+tools:
+- name: Git
+  description: Fast, scalable, distributed revision control system
+  website_url: http://git-scm.com/
+  open_source: true
+  hosted_saas: false
+  category: Build, Test, Deploy
+  sub_category: Version Control System
+  image_url: https://img.stackshare.io/service/1046/git.png
+  detection_source_url: https://github.com/Meter-Reader/yard_rails_plugin
+  detection_source: Repo Metadata

data/templates/default/class/html/routes.erb

@@ -0,0 +1,13 @@
+<% if object[:routes] %>
+<div class="tags">
+  <h2>Routes</h2>
+  <ul class="routes method_details_list">
+    <% for r in object[:routes] %>
+		<li>[<%= r[:verb] %>] <%= r[:path].gsub(/(:|\*)\w+/) { |m| "<span style='font-family: monospace; color: green'>#{m}</span>"} %>
+			&raquo; <%= r[:rack_app] ? "<pre>#{r[:rack_app].inspect}</pre>" : link_object(P("#{r[:controller]}##{r[:action]}"), '#' + r[:action]) %>
+			 <%= (r[:name] && !r[:name].empty? ? "<span style='font-size: 85%'>(Rails Method: #{r[:name]})</span>" : '') %>
+		</li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/templates/default/class/setup.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+def init
+  super
+  sections.place(:routes).before(:children)
+end

data/templates/default/method_details/html/params.erb

@@ -0,0 +1,10 @@
+<% if object[:params] %>
+<div class="tags">
+  <h3>Params:</h3>
+  <ul class="params">
+    <% for p in object[:params] %>
+		<li>params[<%= link_object(P(p.gsub(':','').gsub("'",'').capitalize), p )%>]</li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/templates/default/method_details/html/routes.erb

@@ -0,0 +1,12 @@
+<% if object[:routes] %>
+<div class="tags">
+  <h3>Routes:</h3>
+  <ul class="routes">
+    <% for r in object[:routes] %>
+		<li>[<%= r[:verb] %>] <%= r[:path].gsub(/(:|\*)\w+/) { |m| "<span style='font-family: monospace; color: green'>#{m}</span>"} %>
+			 <%= (r[:name] && !r[:name].empty? ? "<span style='font-size: 85%'>(Rails Method: #{r[:name]})</span>" : '') %>
+		</li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/templates/default/method_details/setup.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+def init
+  super
+  sections.last.place(:routes).before(:source)
+  sections.last.place(:params).after(:routes)
+end

data/yard-rails-plugin.gemspec

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'English'
+require File.expand_path('lib/yard-rails_plugin/version', __dir__)
+
+Gem::Specification.new do |gem|
+  gem.required_ruby_version = '~> 3.3'
+  gem.authors       = ['Peter Nagy']
+  gem.email         = ['peter@meter-reader.com']
+  gem.summary       = 'YARD plugin to document a Rails project'
+  gem.homepage      = 'https://github.com/Meter-reader/yard-rails_plugin'
+  gem.licenses      = ['MIT']
+
+  gem.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = 'yard-rails_plugin'
+  gem.require_paths = ['lib']
+  gem.version       = YARD::Rails::Plugin::VERSION
+
+  gem.add_runtime_dependency 'yard', '~> 0.7', '> 0.7'
+  gem.add_development_dependency 'rake', '~> 13.2'
+  gem.add_development_dependency 'rubocop', '~> 1.63'
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: yard-rails_plugin
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Peter Nagy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.63'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.63'
+description: 
+email:
+- peter@meter-reader.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/gem-push.yml"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/yard-rails_plugin.rb
+- lib/yard-rails_plugin/controller_params_handler.rb
+- lib/yard-rails_plugin/routes.rb
+- lib/yard-rails_plugin/version.rb
+- techstack.md
+- techstack.yml
+- templates/default/class/html/routes.erb
+- templates/default/class/setup.rb
+- templates/default/method_details/html/params.erb
+- templates/default/method_details/html/routes.erb
+- templates/default/method_details/setup.rb
+- yard-rails-plugin.gemspec
+homepage: https://github.com/Meter-reader/yard-rails_plugin
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key: 
+specification_version: 4
+summary: YARD plugin to document a Rails project
+test_files: []