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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9c561fb4adb1a813dee7cc4f1793ecee708627115f85aab396933822e4886cb0
4
- data.tar.gz: 17e36c633008becd1b8ead5af645e58182d5be5959736cfb34280f4c7a077848
3
+ metadata.gz: 45d1e77bad42779c78eb819361eeef638e1eb6a6b622ef7f850298258a4cbf14
4
+ data.tar.gz: 715a1015c9d12f9ccdd13e9afe20f70e3b566dc9996161b8cedfcc7eecbcc9bf
5
5
  SHA512:
6
- metadata.gz: 1c472b473610259d5067deceacbdc08ba3e2f68b00e07947d9b0aa55657623d28fccaf65237f213fc01f03b1f5d4674094fdfbe825f1829d17dadcc6c6efec69
7
- data.tar.gz: abd879a66a9334c633120f9a1ee486cffa42dd4d08b184fe321bbea27a6f002a626b9adb76c46efc5637a3d489e3f365bdbea6b75f9901b3a22f8694bd73fbcc
6
+ metadata.gz: c813cfeaad842d55c9b4573fa91f025ac07d78b8bb512a45f32af671a25c213d34e4291c6346ab0e43e141fab89dd82ba5ca279760e17b4ac06a1f042c39fd26
7
+ data.tar.gz: 4080476f10d33d9d98c39ca2d04e4834c2a1ef8308451ad102022991286f88e4f42bba1fbdf5ddac53a1c16ad3cb40fa53eb656b72d59d5155a6e6ea589db4d6
data/.streerc ADDED
@@ -0,0 +1,2 @@
1
+ --print-width=100
2
+ --plugins=plugin/trailing_comma,disable_ternary
data/README.md CHANGED
@@ -1,25 +1,32 @@
1
1
  # Yard::Markdown
2
2
 
3
- Yard theme plugin that generates markdown documentation for gems
3
+ Yard plugin to generate markdown documentation
4
4
 
5
5
  ## Goals:
6
6
  - Compatible with Github Flavored Markdown
7
- - Mimick yard html layout in markdown format as much as possible
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
- Add these lines:
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 'yard-markdown'
23
+ gem install yard-markdown
14
24
  ```
15
- And run `bundle install`
16
25
 
17
- Run yardoc with `--format=markdown --plugin=markdown` parameters.
26
+ Run `yardoc --format=markdown` to generate markdown documentation.
18
27
 
19
28
  ## Backstory
20
- Successor to rdoc-mardown gem that was authored by me. So there is a lot of similarities between two - [example](https://github.com/skatkov/rdoc-markdown/tree/main/example).
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 "standard/rake"
12
+ require "syntax_tree/rake_tasks"
13
+ SyntaxTree::Rake::CheckTask.new
14
+ SyntaxTree::Rake::WriteTask.new
13
15
 
14
- task default: %i[test standard]
16
+ task default: %i[test stree:write]
data/lib/yard-markdown.rb CHANGED
@@ -7,4 +7,4 @@ module YARD
7
7
  end
8
8
  end
9
9
 
10
- YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
10
+ YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + "/../templates"
@@ -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
- def init
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) do
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, 'wb') do |csv|
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, 'Class', options.serializer.serialized_path(object)]
45
+ csv << [object.name, "Class", options.serializer.serialized_path(object)]
51
46
  elsif object.type == :module
52
- csv << [object.name, 'Module', options.serializer.serialized_path(object)]
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 { |cnst| csv << [cnst.name(false), 'Constant', (options.serializer.serialized_path(object) + "#" +aref(cnst))] }
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 { |item| csv << [item.name(false), 'Method', options.serializer.serialized_path(object) + "#" + aref(item)] }
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 { |item| csv << [item.name(false), 'Method', options.serializer.serialized_path(object) + '#' + aref(item)]}
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 { |item| csv << [item.name(false), 'Attribute', options.serializer.serialized_path(object) + "#" + aref(item)]}
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 = ERB.new('# <%= format_object_title object %>
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
- (<%= cnst.value %>) <%= cnst.docstring %>
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(/^ /, ''), trim_mode: '%<>')
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(object.meths(inherited: false, visibility: [:public]), included: false).sort_by { |m| m.name.to_s }
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.inheritance_tree(true).each do |superclass|
170
- next if superclass.is_a?(CodeObjects::Proxy)
171
- next if !options.embed_mixins.empty? &&
172
- !options.embed_mixins_match?(superclass)
173
- [:class, :instance].each do |scope|
174
- superclass.attributes[scope].each do |_name, rw|
175
- attr = prune_method_listing([rw[:read], rw[:write]].compact, false).first
176
- @attrs << attr if attr
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 do |itm|
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.0
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: 2023-12-05 00:00:00.000000000 Z
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
- - ".standard.yml"
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.22
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
@@ -1,3 +0,0 @@
1
- # For available configuration options, see:
2
- # https://github.com/testdouble/standard
3
- ruby_version: 2.6