user_docs 0.3.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 479708398a4aad02dd98ddb186eef5c936b8838dc2680a9cc7d0a55908238d73
4
- data.tar.gz: bb388526212fcfc90e4a66d6a37bb1657180f17acec9a1673f1adc393790b27f
3
+ metadata.gz: 849b042e18e7828b3c9ddfc27ed4e91c2dd27a173e340207f4c2cfe344945692
4
+ data.tar.gz: 1d66be1ffade7ce1df335826fe15af8c183c40bb8440bc3d7bb01903793c883f
5
5
  SHA512:
6
- metadata.gz: ad34fca7912ec5bf2be9ff3568a285d32ea9439b161f8feaf4f78c2939c346c6839a3f040096aaaaa23435f1cf8d3b3a331e607cf99a5cb99e7b4aa2e47a6846
7
- data.tar.gz: 712e73ded00f2231327966f3bddcb7cae93af8783ad5e43c2e05d2fbca930bdbc6ebb567c7d085f836ed110860fbd868f5a404526ef2917adc5fee9a14cdced2
6
+ metadata.gz: b522e44a349e0772df9f00455a7191315f245ab7499669ffd41de91565f55bbb25141b6cc584e44f7f0fd98c78ed19ad2556fa82a0a2b247f9389941e2fa2f66
7
+ data.tar.gz: 594b24f70aad792d1f0952fcc3a1f7e14b633d0661d9da9c39574d5c21f12d10be6274a9d17c3f24ac4fa90a3557d8df371ae951cfb2a65647feefb32618e663
data/README.md CHANGED
@@ -3,43 +3,35 @@ UserDocs is an semi-autonomous way to create end-user documentation for your Rai
3
3
 
4
4
  ## Installation
5
5
  0. Ensure you have the VERSION constant defined for your project.
6
- 1. Add this line to your application's Gemfile:
7
- ```ruby
8
- gem 'user_docs'
9
- ```
10
- And then execute:
11
- ```bash
12
- $ bundle
13
- ```
14
- 3. Install the required files:
15
- ```bash
16
- $ rails g user_docs:install
17
- ```
18
- 4. Include the UserDocs module in your system tests:
19
- ```ruby
20
- class ExampleTest < ApplicationSystemTestCase
21
- include UserDocs
22
-
23
- test "foo" do
24
- end
25
- end
26
- ```
27
- 5. Generate documentation by running your system tests:
28
- ```bash
29
- $ rails test:system
30
- ```
31
- 6. Push changes to master.
32
- 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)
33
- 8. Your documentation should be viewable in the given url within a couple minutes.
6
+ 1. Add this line to your application's Gemfile: `gem 'user_docs'`
7
+ 2. And then execute: `bundle`
8
+ 3. Create procedures, for example: `/docs/feature_two_procedure.rb`
9
+
10
+ #!ruby
11
+ require_relative '../test/application_system_test_case.rb'
12
+
13
+ class FeatureOneProcedure < ApplicationSystemTestCase
14
+ include UserDocs
15
+
16
+ test 'action one' do
17
+ visit '/'
18
+ accept_alert
19
+ comment 'Hotel'
20
+ end
21
+ end
22
+
23
+ 4. Generate documentation by running your system tests: `rails user_docs:build_site`
24
+ 5. Documentation viewable at `/docs`
34
25
 
35
26
  ## Usage
36
27
  Here are the following methods you can use to create documentation:
37
- * `accept_alert`
38
- * `click_on`
39
- * `fill_in`
40
- * `choose`
41
- * `save_screenshot`
42
- * `comment`
28
+
29
+ * `accept_alert`
30
+ * `click_on`
31
+ * `fill_in`
32
+ * `choose`
33
+ * `save_screenshot`
34
+ * `comment`
43
35
 
44
36
  ## License
45
37
  The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -10,11 +10,11 @@ module UserDocs
10
10
  def create
11
11
  check_for_version
12
12
 
13
- template "index", "docs/index.html"
14
- template "_layouts/default", "docs/_layouts/default.html"
15
- template "_includes/index", "docs/_includes/index.html"
16
- empty_directory "docs/_data/versions"
17
- empty_directory "docs/versions"
13
+ template "index", ".docs/index.html"
14
+ template "_layouts/default", ".docs/_layouts/default.html"
15
+ template "_includes/index", ".docs/_includes/index.html"
16
+ empty_directory ".docs/_data/versions"
17
+ empty_directory ".docs/versions"
18
18
  end
19
19
 
20
20
  private
@@ -2,7 +2,7 @@
2
2
 
3
3
  {% assign version_directory = page.version | default: site.version | replace: '.', '_' %}
4
4
  {% for feature in site.data.versions[version_directory] %}
5
- <h2 class="mt-3">{{feature[0]}}</h2>
5
+ <h2 class="mt-3">{{feature[0] | replace: '_', ' ' | capitalize}}</h2>
6
6
 
7
7
  <div class="accordian" id="{{feature[0]}}">
8
8
  {% for methods in feature[1] %}
@@ -4,13 +4,13 @@
4
4
  <head>
5
5
  <meta charset="utf-8">
6
6
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
7
- <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
7
+ <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous">
8
8
  <title>End User Documentation</title>
9
9
  </head>
10
10
 
11
11
  <body class="container">
12
12
  <nav class="navbar navbar-expand-lg navbar-light bg-light rounded">
13
- <a class="navbar-brand" href="index.html">End User Documentation v{{ current_page_version }}</a>
13
+ <a class="navbar-brand" href="{{ 'index.html' | relative_url }}">End User Documentation v{{ current_page_version }}</a>
14
14
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
15
15
  <span class="navbar-toggler-icon"></span>
16
16
  </button>
@@ -24,7 +24,7 @@
24
24
  <div class="dropdown-menu" aria-labelledby="navbarDropdown">
25
25
  {% for version in site.data.versions %}
26
26
  {% assign dot_version = version.first | replace: '_', '.' %}
27
- {% assign version_path = "/versions/" | append: dot_version %}
27
+ {% assign version_path = "/versions/" | append: version.first %}
28
28
  {% assign css_class = "" %}
29
29
  {% if dot_version == current_page_version %}
30
30
  {% assign css_class = " active" %}
@@ -37,8 +37,8 @@
37
37
  </div>
38
38
  </nav>
39
39
  {{ content }}
40
- <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
41
- <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>
42
- <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
40
+ <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
41
+ <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
42
+ <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
43
43
  </body>
44
44
  </html>
@@ -3,24 +3,16 @@
3
3
  namespace :user_docs do
4
4
  desc "Build site"
5
5
  task build_site: :environment do
6
- check_installation
7
-
6
+ procedures_dir = Rails.root.join("docs")
7
+ hidden_dir = Rails.root.join(".docs")
8
8
  output_dir = Rails.root.join("public/docs")
9
- FileUtils.mkdir_p(output_dir)
10
- system("cd docs && jekyll build -b /docs")
11
- FileUtils.mv(
12
- Dir.glob(Rails.root.join("docs/_site/*")), output_dir, force: true
13
- )
14
- FileUtils.remove_dir(Rails.root.join("docs/_site"))
15
- end
16
-
17
- private
18
9
 
19
- def check_installation
20
- return if Dir.exist?(Rails.root.join("docs"))
10
+ Rails::Generators.invoke("user_docs:install") unless Dir.exist?(hidden_dir)
21
11
 
22
- # :nocov:
23
- abort("ERROR: Run 'rails g user_docs:install.'")
24
- # :nocov:
12
+ system("rails test #{procedures_dir}/*")
13
+ system <<~CMD.squish
14
+ jekyll build
15
+ --source #{hidden_dir} --destination #{output_dir} --baseurl /docs
16
+ CMD
25
17
  end
26
18
  end
@@ -11,22 +11,19 @@ module UserDocs
11
11
 
12
12
  check_installation
13
13
 
14
- @class_name = class_name.chomp("Test")
14
+ @class_name = class_name.chomp("Procedure")
15
15
  @method = name.sub("test_", "")
16
16
  make_version_data_directory
17
17
  make_version_index
18
- Capybara.save_path = Rails.root.join("docs", "assets", @class_name, @method)
18
+ Capybara.save_path =
19
+ Rails.root.join(".docs/assets/#{version}/#{klass_name}/#{@method}")
19
20
 
20
21
  @json = { name: @method.humanize, steps: [] }
21
22
  end
22
23
 
23
24
  def before_teardown
24
- File.write(
25
- Rails.root.join(
26
- "docs", "_data", "versions", version_data_directory_name,
27
- @class_name, "#{@method}.json"
28
- ), @json.to_json
29
- )
25
+ path = ".docs/_data/versions/#{version}/#{klass_name}/#{@method}.json"
26
+ File.write(Rails.root.join(path), @json.to_json)
30
27
 
31
28
  super
32
29
  end
@@ -42,37 +39,36 @@ module UserDocs
42
39
  end
43
40
 
44
41
  def version
45
- Rails.application.class.module_parent::VERSION
42
+ Rails.application.class.module_parent::VERSION.tr(".", "_")
46
43
  end
47
44
 
48
- def version_data_directory_name
49
- version.tr(".", "_")
45
+ def klass_name
46
+ @class_name.underscore
50
47
  end
51
48
 
52
49
  def make_version_data_directory
53
- FileUtils.mkdir_p(
54
- Rails.root.join("docs", "_data", "versions",
55
- version_data_directory_name, @class_name)
56
- )
50
+ data_path = Rails.root.join(".docs/_data/versions/#{version}/#{klass_name}")
51
+ FileUtils.mkdir_p(data_path)
57
52
  end
58
53
 
59
54
  # rubocop:disable Metrics/MethodLength
60
55
  def make_version_index
61
- directory = "#{Rails.root}/docs/versions/#{version}"
62
- FileUtils.mkdir_p directory
63
- output_file = "#{directory}/index.html"
56
+ directory = Rails.root.join(".docs/versions/#{version}")
57
+ output_file = directory + "index.html"
58
+ entry_file = Rails.root.join(".docs/index.html")
59
+
60
+ FileUtils.mkdir_p(directory)
64
61
  File.write(
65
62
  output_file,
66
63
  <<~HTML
67
64
  ---
68
65
  layout: default
69
- version: #{version}
66
+ version: #{version.tr!('_', '.')}
70
67
  ---
71
68
  {% include index.html %}
72
69
  HTML
73
70
  )
74
71
 
75
- entry_file = Rails.root.join("docs/index.html")
76
72
  FileUtils.cp_r(output_file, entry_file, remove_destination: true)
77
73
  end
78
74
  # rubocop:enable Metrics/MethodLength
@@ -97,10 +93,12 @@ module UserDocs
97
93
  @json[:steps] << "Click **OK**."
98
94
  end
99
95
 
100
- def save_screenshot(image)
96
+ def save_screenshot(image = Time.now.to_i.to_s)
97
+ image += ".png"
101
98
  super
102
- @json[:steps] <<
103
- "<img src='assets/#{@class_name}/#{@method}/#{image}' class='img-fluid'>"
99
+
100
+ path = "/docs/assets/#{version}/#{klass_name}/#{@method}/#{image}"
101
+ @json[:steps] << "<img src='#{path}' class='img-fluid'>"
104
102
  end
105
103
 
106
104
  def comment(string)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module UserDocs
4
- VERSION = "0.3.0"
4
+ VERSION = "0.8.0"
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: user_docs
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0
4
+ version: 0.8.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - jtopgi
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2020-05-20 00:00:00.000000000 Z
11
+ date: 2020-06-01 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: capybara