user_docs 0.0.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67c39c53388cf78f7f03ff632552792d7946a09d990cf7e71ef63e96ebe7d126
-  data.tar.gz: e1545d408a3d543b43ff274786bfeb7dfa61c46013d9cf9e69f564aacc91c775
+  metadata.gz: 17570ca7f142aca7a866a337055a720d2acae9ea4c851f0b9a6b8ca3274c5be9
+  data.tar.gz: 7b7226c0791a3256f6c718d5388d001c9cab842e9798fe5b32ef02b4e32f532e
 SHA512:
-  metadata.gz: c348ff79b487bd6fa2995555ec2eaac4ff4c10bfe71980463340d8ad335636cd8466848993b0d126612e748e3106dfc30313c345aee714a7c686e0b601cde966
-  data.tar.gz: 9d650d9b7cea0d59daa4dc4d1ae7ae152001fe85cb1dda66aef591f9a51674347885c45bb55961b1dcb3a7cbd2a574e170d6d4b3cb94e45a0ffa34849a9cdada
+  metadata.gz: bff557e8d7dc2f577bbd9789c1f4bd928f45b776cb7b4f824303d2513e20a4498ec439f90eee27c29d0589f30f586b3b224226f76a4251a37a60ef534a5c2b2f
+  data.tar.gz: 94710b2d8796ab802bf14068787ea5dccc007477289b0b42a0a13e7a30be1394c153e403bd2fbeb2b35df99ed3d9bc07282384844b3f861a8d231dc0fc301f83

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 jtopgi
+
+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,45 @@
+# UserDocs
+UserDocs is an semi-autonomous way to create end-user documentation for your Rails project.
+
+## Installation
+0. Ensure you have the VERSION constant defined for your project.
+1. Add this line to your application's Gemfile:
+   ```ruby
+   gem 'user_docs'
+   ```
+   And then execute:
+   ```bash
+   $ bundle
+   ```
+3. Install the required files:
+   ```bash
+   $ rails g user_docs:install
+   ```
+4. Include the UserDocs module in your system tests:
+   ```ruby
+   class ExampleTest < ApplicationSystemTestCase
+     include UserDocs
+
+     test "foo" do
+     end
+   end
+   ```
+5. Generate documentation by running your system tests:
+   ```bash
+   $ rails test:system
+   ```
+6. Push changes to master.
+7. [Enable GitHub Pages docs folder.](https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch)
+8. Your documentation should be viewable in the given url within a couple minutes.
+
+## Usage
+Here are the following methods you can use to create documentation:
+* `accept_alert`
+* `click_on`
+* `fill_in`
+* `choose`
+* `save_screenshot`
+* `comment`
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "UserDocs"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/generators/*_test.rb", "test/integration/*_test.rb", "test/system/*_test.rb"]
+  t.verbose = false
+end
+
+require "rubocop/rake_task"
+require "bundler/audit/task"
+RuboCop::RakeTask.new
+Bundler::Audit::Task.new
+
+task :default do
+  Rake::Task[:rubocop].invoke
+  Rake::Task["bundle:audit"].invoke
+  Rake::Task[:test].invoke
+end

data/lib/generators/user_docs/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module UserDocs
+  # Installs the required files
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def create
+      check_for_version
+
+      template "_config", ".docs/_config.yml"
+      template "index", ".docs/index.html"
+      template "_layouts/default", ".docs/_layouts/default.html"
+      template "_includes/index", ".docs/_includes/index.html"
+      empty_directory ".docs/_data/versions"
+      empty_directory ".docs/versions"
+    end
+
+    private
+
+    def check_for_version
+      host_app = Rails.application.class
+      return if defined?(host_app.module_parent::VERSION)
+
+      # :nocov:
+      abort "ERROR: version needs to defined as "\
+            "#{host_app.module_parent}::VERSION."
+      # :nocov:
+    end
+  end
+end

data/lib/generators/user_docs/templates/_config.tt

@@ -0,0 +1 @@
+keep_files: ['versions', 'assets']

data/lib/generators/user_docs/templates/_includes/index.tt

@@ -0,0 +1,24 @@
+<h1 class="text-center">Features</h1>
+
+{% assign version_directory = page.version | default: site.version | replace: '.', '_' %}
+{% for feature in site.data.versions[version_directory] %}
+  <h2 class="mt-3">{{feature[0]}}</h2>
+
+  <div class="accordian" id="{{feature[0]}}">
+    {% for methods in feature[1] %}
+      <div class="card">
+        <button class="btn btn-light btn-lg collapsed text-left" type="button" data-toggle="collapse" data-target="#{{feature[0]}}-collapse-{{forloop.index}}" style="white-space: normal;">{{methods[1].name}}</button>
+        <div id="{{feature[0]}}-collapse-{{forloop.index}}" class="collapse" data-parent="#{{feature[0]}}">
+          <div class="card-body">
+            <ul>
+              {% for step in methods[1].steps %}
+                <li>{{step | markdownify | remove: '<p>' | remove: '</p>'}}</li>
+              {% endfor %}
+            </ul>
+          </div>
+        </div>
+      </div>
+    {% endfor %}
+  </div>
+{% endfor %}
+

data/lib/generators/user_docs/templates/_layouts/default.tt

@@ -0,0 +1,44 @@
+{% assign current_page_version = page.version | default: site.version %}
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous">
+    <title>End User Documentation</title>
+  </head>
+
+  <body class="container">
+    <nav class="navbar navbar-expand-lg navbar-light bg-light rounded">
+      <a class="navbar-brand" href="{{ 'index.html' | relative_url }}">End User Documentation v{{ current_page_version }}</a>
+      <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+
+      <div class="collapse navbar-collapse" id="navbarSupportedContent">
+        <ul class="navbar-nav ml-auto">
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+              Version
+            </a>
+            <div class="dropdown-menu" aria-labelledby="navbarDropdown">
+              {% for version in site.data.versions %}
+                {% assign dot_version = version.first | replace: '_', '.' %}
+                {% assign version_path = "/versions/" | append: dot_version %}
+                {% assign css_class = "" %}
+                {% if dot_version == current_page_version %}
+                  {% assign css_class = " active" %}
+                {% endif %}
+                <a class="dropdown-item{{ css_class }}" href="{{ version_path | relative_url }}">{{ dot_version }}</a>
+              {% endfor %}
+            </div>
+          </li>
+        </ul>
+      </div>
+    </nav>
+    {{ content }}
+    <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
+    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
+  </body>
+</html>

data/lib/generators/user_docs/templates/index.tt

@@ -0,0 +1,5 @@
+---
+layout: default
+---
+
+{% include index.html %}

data/lib/tasks/user_docs_tasks.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+namespace :user_docs do
+  desc "Build site"
+  task build_site: :environment do
+    procedures_dir = Rails.root.join("docs")
+    temp_dir = Rails.root.join(".docs")
+    output_dir = Rails.root.join("public/docs")
+
+    Rails::Generators.invoke("user_docs:install")
+    system("rails test #{procedures_dir}/*")
+    system <<~CMD.squish
+      jekyll build
+      --source #{temp_dir} --destination #{output_dir} --baseurl /docs
+    CMD
+    FileUtils.rm_rf(temp_dir)
+  end
+end

data/lib/user_docs.rb

@@ -1,10 +1,9 @@
-module UserDocs
-  def self.hi
-    puts "Hello world!"
-  end
+# frozen_string_literal: true
+
+require "user_docs/railtie"
+require "user_docs/capybara_extension"
+require "webdrivers"
 
-  def click_on(link)
-    super
-    puts("Click on **#{link}**.")
-  end
+# User Documentation module
+module UserDocs
 end

data/lib/user_docs/capybara_extension.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "capybara"
+
+# Extends Capybara's Actions to create end user documentation
+module UserDocs
+  extend Capybara::Node::Actions
+
+  def before_setup
+    super
+
+    check_installation
+
+    @class_name = class_name.chomp("Procedure")
+    @method = name.sub("test_", "")
+    make_version_data_directory
+    make_version_index
+    Capybara.save_path =
+      Rails.root.join(".docs/assets/#{version}/#{klass_name}/#{@method}")
+
+    @json = { name: @method.humanize, steps: [] }
+  end
+
+  def before_teardown
+    path = ".docs/_data/versions/#{version}/#{klass_name}/#{@method}.json"
+    File.write(Rails.root.join(path), @json.to_json)
+
+    super
+  end
+
+  private
+
+  def check_installation
+    return if Dir.exist?(Rails.root.join("docs"))
+
+    # :nocov:
+    abort("ERROR: Run 'rails g user_docs:install.'")
+    # :nocov:
+  end
+
+  def version
+    Rails.application.class.module_parent::VERSION
+  end
+
+  def klass_name
+    @class_name.underscore
+  end
+
+  def make_version_data_directory
+    data_path = Rails.root.join(".docs/_data/versions/#{version}/#{klass_name}")
+    FileUtils.mkdir_p(data_path)
+  end
+
+  # rubocop:disable Metrics/MethodLength
+  def make_version_index
+    directory = Rails.root.join(".docs/versions/#{version}")
+    output_file = directory + "index.html"
+    entry_file = Rails.root.join(".docs/index.html")
+
+    FileUtils.mkdir_p(directory)
+    File.write(
+      output_file,
+      <<~HTML
+        ---
+        layout: default
+        version: #{version}
+        ---
+        {% include index.html %}
+      HTML
+    )
+
+    FileUtils.cp_r(output_file, entry_file, remove_destination: true)
+  end
+  # rubocop:enable Metrics/MethodLength
+
+  def click_on(link)
+    super
+    @json[:steps] << "Click on **#{link}**."
+  end
+
+  def fill_in(text, with:)
+    super
+    @json[:steps] << "Fill in **#{text}** with *#{with}*."
+  end
+
+  def choose(label)
+    super
+    @json[:steps] << "Select radio button with *#{label}*."
+  end
+
+  def accept_alert
+    page.accept_alert
+    @json[:steps] << "Click **OK**."
+  end
+
+  def save_screenshot(image = Time.now.to_i.to_s)
+    image += ".png"
+    super
+
+    path = "/docs/assets/#{version}/#{klass_name}/#{@method}/#{image}"
+    @json[:steps] << "<img src='#{path}' class='img-fluid'>"
+  end
+
+  def comment(string)
+    @json[:steps] << string
+  end
+end

data/lib/user_docs/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# :nocov:
+module UserDocs
+  # Extend Rails and/or modify the initialization process.
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load "tasks/user_docs_tasks.rake"
+    end
+  end
+end
+# :nocov:

data/lib/user_docs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UserDocs
+  VERSION = "0.6.0"
+end

metadata

@@ -1,41 +1,194 @@
 --- !ruby/object:Gem::Specification
 name: user_docs
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.6.0
 platform: ruby
 authors:
-- Jeevan Topgi
+- jtopgi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-26 00:00:00.000000000 Z
+date: 2020-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.32.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: A gem that creates end user documentation, viewable through Github Pages,
-  through system tests.
-email: jeevan-topgi1@northwestern.edu
+        version: 3.32.1
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3.1
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.142.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.142.7
+- !ruby/object:Gem::Dependency
+  name: webdrivers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.0
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.81.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.81.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.5.2
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.18.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.18.5
+description: 
+email:
+- jtopgi@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/generators/user_docs/install_generator.rb
+- lib/generators/user_docs/templates/_config.tt
+- lib/generators/user_docs/templates/_includes/index.tt
+- lib/generators/user_docs/templates/_layouts/default.tt
+- lib/generators/user_docs/templates/index.tt
+- lib/tasks/user_docs_tasks.rake
 - lib/user_docs.rb
-homepage: http://rubygems.org/gems/user_docs
+- lib/user_docs/capybara_extension.rb
+- lib/user_docs/railtie.rb
+- lib/user_docs/version.rb
+homepage: 
 licenses:
 - MIT
-metadata: {}
+metadata:
+  allowed_push_host: https://rubygems.org
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -51,9 +204,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: UserDocs
+summary: Summary of UserDocs.
 test_files: []