user_docs 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67c39c53388cf78f7f03ff632552792d7946a09d990cf7e71ef63e96ebe7d126
-  data.tar.gz: e1545d408a3d543b43ff274786bfeb7dfa61c46013d9cf9e69f564aacc91c775
+  metadata.gz: 8a29682463845307876f721711cc7c35fb66b740b57fa04c7a2aae82972db7d1
+  data.tar.gz: 1cb0f5c6697ad276f401968f4b342da581d81e33f92e468c1c40862e8c59d48e
 SHA512:
-  metadata.gz: c348ff79b487bd6fa2995555ec2eaac4ff4c10bfe71980463340d8ad335636cd8466848993b0d126612e748e3106dfc30313c345aee714a7c686e0b601cde966
-  data.tar.gz: 9d650d9b7cea0d59daa4dc4d1ae7ae152001fe85cb1dda66aef591f9a51674347885c45bb55961b1dcb3a7cbd2a574e170d6d4b3cb94e45a0ffa34849a9cdada
+  metadata.gz: f3741fb6d581ea85e6ce3f63ae00ba213c2d452a2af19b1a36b2f6c0eba2b09c36cf34ac87d94c75fe94cc451147cf408930ece29024f61f60f45c9f804a7350
+  data.tar.gz: ccda61469eaf5bf01c1cbe52c7abbc4aa325a362cd6b5a4ef8351bf1e38da94f75411f820a295eb19565f4022321f3dd8dd04921e1d38ad7e4e09af8da0aca00

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,32 @@
+# 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 "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/_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.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" 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">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.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
+    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" 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,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :user_docs do
+#   # Task goes here
+# 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,105 @@
+# 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("Test")
+    @method = name.sub("test_", "")
+    make_version_data_directory
+    make_version_index
+    Capybara.save_path = Rails.root.join("docs", "assets", @class_name, @method)
+
+    @json = { name: @method.humanize, steps: [] }
+  end
+
+  def before_teardown
+    File.write(
+      Rails.root.join(
+        "docs", "_data", "versions", version_data_directory_name,
+        @class_name, "#{@method}.json"
+      ), @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 version_data_directory_name
+    version.tr(".", "_")
+  end
+
+  def make_version_data_directory
+    FileUtils.mkdir_p(
+      Rails.root.join("docs", "_data", "versions",
+                      version_data_directory_name, @class_name)
+    )
+  end
+
+  # rubocop:disable Metrics/MethodLength
+  def make_version_index
+    directory = "#{Rails.root}/docs/versions/#{version}"
+    FileUtils.mkdir_p directory
+    File.write(
+      "#{directory}/index.html",
+      <<~HTML
+        ---
+        layout: default
+        version: #{version}
+        ---
+        {% include index.html %}
+      HTML
+    )
+  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)
+    super
+    @json[:steps] <<
+      "<img src='assets/#{@class_name}/#{@method}/#{image}' class='img-fluid'>"
+  end
+
+  def comment(string)
+    @json[:steps] << string
+  end
+end

data/lib/user_docs/railtie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module UserDocs
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/user_docs/version.rb

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

metadata

@@ -1,41 +1,179 @@
 --- !ruby/object:Gem::Specification
 name: user_docs
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.2.0
 platform: ruby
 authors:
-- Jeevan Topgi
+- jtopgi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-26 00:00:00.000000000 Z
+date: 2020-05-19 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: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+- !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/_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 +189,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: []