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 +4 -4
- data/README.md +26 -34
- data/lib/generators/user_docs/install_generator.rb +5 -5
- data/lib/generators/user_docs/templates/_includes/index.tt +1 -1
- data/lib/generators/user_docs/templates/_layouts/default.tt +6 -6
- data/lib/tasks/user_docs_tasks.rake +8 -16
- data/lib/user_docs/capybara_extension.rb +21 -23
- data/lib/user_docs/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 849b042e18e7828b3c9ddfc27ed4e91c2dd27a173e340207f4c2cfe344945692
|
4
|
+
data.tar.gz: 1d66be1ffade7ce1df335826fe15af8c183c40bb8440bc3d7bb01903793c883f
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
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
|
-
|
38
|
-
*
|
39
|
-
*
|
40
|
-
*
|
41
|
-
*
|
42
|
-
*
|
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.
|
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:
|
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.
|
41
|
-
<script src="https://
|
42
|
-
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.
|
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
|
-
|
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
|
-
|
20
|
-
return if Dir.exist?(Rails.root.join("docs"))
|
10
|
+
Rails::Generators.invoke("user_docs:install") unless Dir.exist?(hidden_dir)
|
21
11
|
|
22
|
-
#
|
23
|
-
|
24
|
-
|
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("
|
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 =
|
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
|
-
|
25
|
-
|
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
|
49
|
-
|
45
|
+
def klass_name
|
46
|
+
@class_name.underscore
|
50
47
|
end
|
51
48
|
|
52
49
|
def make_version_data_directory
|
53
|
-
|
54
|
-
|
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 =
|
62
|
-
|
63
|
-
|
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
|
-
|
103
|
-
|
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)
|
data/lib/user_docs/version.rb
CHANGED
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.
|
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-
|
11
|
+
date: 2020-06-01 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: capybara
|