user_docs 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 479708398a4aad02dd98ddb186eef5c936b8838dc2680a9cc7d0a55908238d73
-  data.tar.gz: bb388526212fcfc90e4a66d6a37bb1657180f17acec9a1673f1adc393790b27f
+  metadata.gz: 849b042e18e7828b3c9ddfc27ed4e91c2dd27a173e340207f4c2cfe344945692
+  data.tar.gz: 1d66be1ffade7ce1df335826fe15af8c183c40bb8440bc3d7bb01903793c883f
 SHA512:
-  metadata.gz: ad34fca7912ec5bf2be9ff3568a285d32ea9439b161f8feaf4f78c2939c346c6839a3f040096aaaaa23435f1cf8d3b3a331e607cf99a5cb99e7b4aa2e47a6846
-  data.tar.gz: 712e73ded00f2231327966f3bddcb7cae93af8783ad5e43c2e05d2fbca930bdbc6ebb567c7d085f836ed110860fbd868f5a404526ef2917adc5fee9a14cdced2
+  metadata.gz: b522e44a349e0772df9f00455a7191315f245ab7499669ffd41de91565f55bbb25141b6cc584e44f7f0fd98c78ed19ad2556fa82a0a2b247f9389941e2fa2f66
+  data.tar.gz: 594b24f70aad792d1f0952fcc3a1f7e14b633d0661d9da9c39574d5c21f12d10be6274a9d17c3f24ac4fa90a3557d8df371ae951cfb2a65647feefb32618e663

data/README.md

@@ -3,43 +3,35 @@ UserDocs is an semi-autonomous way to create end-user documentation for your Rai
 
 ## 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.
+1. Add this line to your application's Gemfile: `gem 'user_docs'`
+2. And then execute: `bundle`
+3. Create procedures, for example: `/docs/feature_two_procedure.rb`
+
+        #!ruby
+        require_relative '../test/application_system_test_case.rb'
+
+        class FeatureOneProcedure < ApplicationSystemTestCase
+          include UserDocs
+
+          test 'action one' do
+            visit '/'
+            accept_alert
+            comment 'Hotel'
+          end
+        end
+
+4. Generate documentation by running your system tests: `rails user_docs:build_site`
+5. Documentation viewable at `/docs`
 
 ## Usage
 Here are the following methods you can use to create documentation:
-* `accept_alert`
-* `click_on`
-* `fill_in`
-* `choose`
-* `save_screenshot`
-* `comment`
+
+*  `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/lib/generators/user_docs/install_generator.rb

@@ -10,11 +10,11 @@ module UserDocs
     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"
+      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

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

@@ -2,7 +2,7 @@
 
 {% assign version_directory = page.version | default: site.version | replace: '.', '_' %}
 {% for feature in site.data.versions[version_directory] %}
-  <h2 class="mt-3">{{feature[0]}}</h2>
+  <h2 class="mt-3">{{feature[0] | replace: '_', ' ' | capitalize}}</h2>
 
   <div class="accordian" id="{{feature[0]}}">
     {% for methods in feature[1] %}

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

@@ -4,13 +4,13 @@
   <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">
+    <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">End User Documentation v{{ current_page_version }}</a>
+      <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>
@@ -24,7 +24,7 @@
             <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 version_path = "/versions/" | append: version.first %}
                 {% assign css_class = "" %}
                 {% if dot_version == current_page_version %}
                   {% assign css_class = " active" %}
@@ -37,8 +37,8 @@
       </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>
+    <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/tasks/user_docs_tasks.rake

@@ -3,24 +3,16 @@
 namespace :user_docs do
   desc "Build site"
   task build_site: :environment do
-    check_installation
-
+    procedures_dir = Rails.root.join("docs")
+    hidden_dir = Rails.root.join(".docs")
     output_dir = Rails.root.join("public/docs")
-    FileUtils.mkdir_p(output_dir)
-    system("cd docs && jekyll build -b /docs")
-    FileUtils.mv(
-      Dir.glob(Rails.root.join("docs/_site/*")), output_dir, force: true
-    )
-    FileUtils.remove_dir(Rails.root.join("docs/_site"))
-  end
-
-  private
 
-  def check_installation
-    return if Dir.exist?(Rails.root.join("docs"))
+    Rails::Generators.invoke("user_docs:install") unless Dir.exist?(hidden_dir)
 
-    # :nocov:
-    abort("ERROR: Run 'rails g user_docs:install.'")
-    # :nocov:
+    system("rails test #{procedures_dir}/*")
+    system <<~CMD.squish
+      jekyll build
+      --source #{hidden_dir} --destination #{output_dir} --baseurl /docs
+    CMD
   end
 end

data/lib/user_docs/capybara_extension.rb

@@ -11,22 +11,19 @@ module UserDocs
 
     check_installation
 
-    @class_name = class_name.chomp("Test")
+    @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", @class_name, @method)
+    Capybara.save_path =
+      Rails.root.join(".docs/assets/#{version}/#{klass_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
-    )
+    path = ".docs/_data/versions/#{version}/#{klass_name}/#{@method}.json"
+    File.write(Rails.root.join(path), @json.to_json)
 
     super
   end
@@ -42,37 +39,36 @@ module UserDocs
   end
 
   def version
-    Rails.application.class.module_parent::VERSION
+    Rails.application.class.module_parent::VERSION.tr(".", "_")
   end
 
-  def version_data_directory_name
-    version.tr(".", "_")
+  def klass_name
+    @class_name.underscore
   end
 
   def make_version_data_directory
-    FileUtils.mkdir_p(
-      Rails.root.join("docs", "_data", "versions",
-                      version_data_directory_name, @class_name)
-    )
+    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}/docs/versions/#{version}"
-    FileUtils.mkdir_p directory
-    output_file = "#{directory}/index.html"
+    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}
+        version: #{version.tr!('_', '.')}
         ---
         {% include index.html %}
       HTML
     )
 
-    entry_file = Rails.root.join("docs/index.html")
     FileUtils.cp_r(output_file, entry_file, remove_destination: true)
   end
   # rubocop:enable Metrics/MethodLength
@@ -97,10 +93,12 @@ module UserDocs
     @json[:steps] << "Click **OK**."
   end
 
-  def save_screenshot(image)
+  def save_screenshot(image = Time.now.to_i.to_s)
+    image += ".png"
     super
-    @json[:steps] <<
-      "<img src='assets/#{@class_name}/#{@method}/#{image}' class='img-fluid'>"
+
+    path = "/docs/assets/#{version}/#{klass_name}/#{@method}/#{image}"
+    @json[:steps] << "<img src='#{path}' class='img-fluid'>"
   end
 
   def comment(string)

data/lib/user_docs/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: user_docs
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.8.0
 platform: ruby
 authors:
 - jtopgi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-20 00:00:00.000000000 Z
+date: 2020-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara