yard-markdown 0.2.0 → 0.2.1
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/.streerc +2 -0
- data/README.md +16 -9
- data/Rakefile +4 -2
- data/lib/yard-markdown.rb +1 -1
- data/templates/default/fulldoc/markdown/setup.rb +59 -40
- metadata +4 -4
- data/.standard.yml +0 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 45d1e77bad42779c78eb819361eeef638e1eb6a6b622ef7f850298258a4cbf14
|
4
|
+
data.tar.gz: 715a1015c9d12f9ccdd13e9afe20f70e3b566dc9996161b8cedfcc7eecbcc9bf
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c813cfeaad842d55c9b4573fa91f025ac07d78b8bb512a45f32af671a25c213d34e4291c6346ab0e43e141fab89dd82ba5ca279760e17b4ac06a1f042c39fd26
|
7
|
+
data.tar.gz: 4080476f10d33d9d98c39ca2d04e4834c2a1ef8308451ad102022991286f88e4f42bba1fbdf5ddac53a1c16ad3cb40fa53eb656b72d59d5155a6e6ea589db4d6
|
data/.streerc
ADDED
data/README.md
CHANGED
@@ -1,25 +1,32 @@
|
|
1
1
|
# Yard::Markdown
|
2
2
|
|
3
|
-
Yard
|
3
|
+
Yard plugin to generate markdown documentation
|
4
4
|
|
5
5
|
## Goals:
|
6
6
|
- Compatible with Github Flavored Markdown
|
7
|
-
- Mimick yard html layout
|
7
|
+
- Mimick yard html layout where it makes sense to maintain familiarity
|
8
8
|
- Produce .csv index file alonside markdown documentation to act as file index
|
9
|
+
- Include markdown files that are already present in source code.
|
9
10
|
|
10
11
|
## Usage
|
11
|
-
|
12
|
+
Yard doesn't load plugin by default, so you need to load plugin through `~/.yard/config`:
|
13
|
+
|
14
|
+
```yaml
|
15
|
+
!!!yaml
|
16
|
+
load_plugins: true
|
17
|
+
autoload_plugins:
|
18
|
+
- markdown
|
19
|
+
```
|
20
|
+
|
21
|
+
Install a plugin
|
12
22
|
```
|
13
|
-
gem
|
23
|
+
gem install yard-markdown
|
14
24
|
```
|
15
|
-
And run `bundle install`
|
16
25
|
|
17
|
-
Run yardoc
|
26
|
+
Run `yardoc --format=markdown` to generate markdown documentation.
|
18
27
|
|
19
28
|
## Backstory
|
20
|
-
|
21
|
-
|
22
|
-
This gem is used by documentation reviewing tool called [POSH TUI](https://poshtui.com)
|
29
|
+
This is a successor to [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdown/tree/main/example) with small differences in implementation. This gem was written to power API documentation browser CLI app for ruby developers called [POSH TUI](https://poshtui.com).
|
23
30
|
|
24
31
|
## Testing
|
25
32
|
Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.
|
data/Rakefile
CHANGED
@@ -9,6 +9,8 @@ Rake::TestTask.new(:test) do |t|
|
|
9
9
|
t.test_files = FileList["test/**/test_*.rb"]
|
10
10
|
end
|
11
11
|
|
12
|
-
require "
|
12
|
+
require "syntax_tree/rake_tasks"
|
13
|
+
SyntaxTree::Rake::CheckTask.new
|
14
|
+
SyntaxTree::Rake::WriteTask.new
|
13
15
|
|
14
|
-
task default: %i[test
|
16
|
+
task default: %i[test stree:write]
|
data/lib/yard-markdown.rb
CHANGED
@@ -3,11 +3,11 @@
|
|
3
3
|
# https://github.com/lsegal/yard/blob/2d197a381c5d4cc5c55b2c60fff992b31c986361/docs/CodeObjects.md
|
4
4
|
|
5
5
|
require "erb"
|
6
|
+
require "csv"
|
6
7
|
|
7
|
-
|
8
|
-
# here I need to copy README.md if there is one.
|
9
|
-
# I also need to write index.md files
|
8
|
+
include Helpers::ModuleHelper
|
10
9
|
|
10
|
+
def init
|
11
11
|
options.objects = objects = run_verifier(options.objects)
|
12
12
|
|
13
13
|
options.delete(:objects)
|
@@ -21,9 +21,7 @@ def init
|
|
21
21
|
next if object.name == :root
|
22
22
|
|
23
23
|
begin
|
24
|
-
Templates::Engine.with_serializer(object, options.serializer)
|
25
|
-
serialize(object)
|
26
|
-
end
|
24
|
+
Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
|
27
25
|
rescue => e
|
28
26
|
path = options.serializer.serialized_path(object)
|
29
27
|
log.error "Exception occurred while generating '#{path}'"
|
@@ -34,45 +32,68 @@ def init
|
|
34
32
|
serialize_index(objects)
|
35
33
|
end
|
36
34
|
|
37
|
-
|
38
|
-
require 'csv'
|
39
|
-
|
40
35
|
def serialize_index(objects)
|
41
36
|
filepath = "#{options.serializer.basepath}/index.csv"
|
42
37
|
|
43
|
-
CSV.open(filepath,
|
38
|
+
CSV.open(filepath, "wb") do |csv|
|
44
39
|
csv << %w[name type path]
|
45
40
|
|
46
41
|
objects.each do |object|
|
47
42
|
next if object.name == :root
|
48
43
|
|
49
44
|
if object.type == :class
|
50
|
-
csv << [object.name,
|
45
|
+
csv << [object.name, "Class", options.serializer.serialized_path(object)]
|
51
46
|
elsif object.type == :module
|
52
|
-
csv << [object.name,
|
47
|
+
csv << [object.name, "Module", options.serializer.serialized_path(object)]
|
53
48
|
end
|
54
49
|
|
55
50
|
if constant_listing.size.positive?
|
56
|
-
constant_listing.each
|
51
|
+
constant_listing.each do |cnst|
|
52
|
+
csv << [
|
53
|
+
cnst.name(false),
|
54
|
+
"Constant",
|
55
|
+
(options.serializer.serialized_path(object) + "#" + aref(cnst)),
|
56
|
+
]
|
57
|
+
end
|
57
58
|
end
|
58
59
|
|
59
60
|
if (insmeths = public_instance_methods(object)).size > 0
|
60
|
-
insmeths.each
|
61
|
+
insmeths.each do |item|
|
62
|
+
csv << [
|
63
|
+
item.name(false),
|
64
|
+
"Method",
|
65
|
+
options.serializer.serialized_path(object) + "#" + aref(item),
|
66
|
+
]
|
67
|
+
end
|
61
68
|
end
|
62
69
|
|
63
70
|
if (pubmeths = public_class_methods(object)).size > 0
|
64
|
-
pubmeths.each
|
71
|
+
pubmeths.each do |item|
|
72
|
+
csv << [
|
73
|
+
item.name(false),
|
74
|
+
"Method",
|
75
|
+
options.serializer.serialized_path(object) + "#" + aref(item),
|
76
|
+
]
|
77
|
+
end
|
65
78
|
end
|
66
79
|
|
67
80
|
if (attrs = attr_listing(object)).size > 0
|
68
|
-
attrs.each
|
81
|
+
attrs.each do |item|
|
82
|
+
csv << [
|
83
|
+
item.name(false),
|
84
|
+
"Attribute",
|
85
|
+
options.serializer.serialized_path(object) + "#" + aref(item),
|
86
|
+
]
|
87
|
+
end
|
69
88
|
end
|
70
89
|
end
|
71
90
|
end
|
72
91
|
end
|
73
92
|
|
74
93
|
def serialize(object)
|
75
|
-
template =
|
94
|
+
template =
|
95
|
+
ERB.new(
|
96
|
+
'# <%= format_object_title object %>
|
76
97
|
| | |
|
77
98
|
| -----------------: | :----- |
|
78
99
|
<% if CodeObjects::ClassObject === object && object.superclass %>
|
@@ -96,7 +117,7 @@ def serialize(object)
|
|
96
117
|
# <%= name %>
|
97
118
|
<% list.each do |cnst| %>
|
98
119
|
## <%= cnst.name %> = [](#<%=aref(cnst)%>)
|
99
|
-
|
120
|
+
<%= cnst.docstring %>
|
100
121
|
<% end %>
|
101
122
|
<% end %>
|
102
123
|
|
@@ -127,7 +148,9 @@ def serialize(object)
|
|
127
148
|
|
128
149
|
<% end %>
|
129
150
|
<% end %>
|
130
|
-
'.gsub(/^ /,
|
151
|
+
'.gsub(/^ /, ""),
|
152
|
+
trim_mode: "%<>",
|
153
|
+
)
|
131
154
|
|
132
155
|
template.result(binding)
|
133
156
|
end
|
@@ -150,10 +173,11 @@ def constant_listing
|
|
150
173
|
@constants
|
151
174
|
end
|
152
175
|
|
153
|
-
include Helpers::ModuleHelper
|
154
|
-
|
155
176
|
def public_method_list(object)
|
156
|
-
prune_method_listing(
|
177
|
+
prune_method_listing(
|
178
|
+
object.meths(inherited: false, visibility: [:public]),
|
179
|
+
included: false,
|
180
|
+
).sort_by { |m| m.name.to_s }
|
157
181
|
end
|
158
182
|
|
159
183
|
def public_class_methods(object)
|
@@ -166,18 +190,19 @@ end
|
|
166
190
|
|
167
191
|
def attr_listing(object)
|
168
192
|
@attrs = []
|
169
|
-
object
|
170
|
-
|
171
|
-
|
172
|
-
|
173
|
-
|
174
|
-
|
175
|
-
|
176
|
-
|
193
|
+
object
|
194
|
+
.inheritance_tree(true)
|
195
|
+
.each do |superclass|
|
196
|
+
next if superclass.is_a?(CodeObjects::Proxy)
|
197
|
+
next if !options.embed_mixins.empty? && !options.embed_mixins_match?(superclass)
|
198
|
+
%i[class instance].each do |scope|
|
199
|
+
superclass.attributes[scope].each do |_name, rw|
|
200
|
+
attr = prune_method_listing([rw[:read], rw[:write]].compact, false).first
|
201
|
+
@attrs << attr if attr
|
202
|
+
end
|
177
203
|
end
|
204
|
+
break if options.embed_mixins.empty?
|
178
205
|
end
|
179
|
-
break if options.embed_mixins.empty?
|
180
|
-
end
|
181
206
|
sort_listing @attrs
|
182
207
|
end
|
183
208
|
|
@@ -193,7 +218,7 @@ def generate_method_list
|
|
193
218
|
end
|
194
219
|
|
195
220
|
def sort_listing(list)
|
196
|
-
list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
|
221
|
+
list.sort_by { |o| [o.scope.to_s, o.name.to_s.downcase] }
|
197
222
|
end
|
198
223
|
|
199
224
|
def groups(list, type = "Method")
|
@@ -208,13 +233,7 @@ def groups(list, type = "Method")
|
|
208
233
|
else
|
209
234
|
others = []
|
210
235
|
group_data = {}
|
211
|
-
list.each
|
212
|
-
if itm.group
|
213
|
-
(group_data[itm.group] ||= []) << itm
|
214
|
-
else
|
215
|
-
others << itm
|
216
|
-
end
|
217
|
-
end
|
236
|
+
list.each { |itm| itm.group ? (group_data[itm.group] ||= []) << itm : others << itm }
|
218
237
|
group_data.each { |group, items| yield(items, group) unless items.empty? }
|
219
238
|
end
|
220
239
|
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: yard-markdown
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.2.
|
4
|
+
version: 0.2.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Stanislav (Stas) Katkov
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2024-01-11 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: yard
|
@@ -32,7 +32,7 @@ extensions: []
|
|
32
32
|
extra_rdoc_files: []
|
33
33
|
files:
|
34
34
|
- ".editorconfig"
|
35
|
-
- ".
|
35
|
+
- ".streerc"
|
36
36
|
- ".yardopts"
|
37
37
|
- LICENSE.txt
|
38
38
|
- README.md
|
@@ -66,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
66
66
|
- !ruby/object:Gem::Version
|
67
67
|
version: '0'
|
68
68
|
requirements: []
|
69
|
-
rubygems_version: 3.4
|
69
|
+
rubygems_version: 3.5.4
|
70
70
|
signing_key:
|
71
71
|
specification_version: 4
|
72
72
|
summary: yard plugin to generate markdown documentation
|
data/.standard.yml
DELETED