readme_yard 0.1.2 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -0
- data/Gemfile.lock +3 -3
- data/README.md +123 -45
- data/README_YARD.md +67 -34
- data/lib/readme_yard.rb +99 -62
- data/lib/readme_yard/comment_tag.rb +41 -0
- data/lib/readme_yard/error.rb +17 -0
- data/lib/readme_yard/example_tag.rb +18 -0
- data/lib/readme_yard/logger.rb +9 -0
- data/lib/readme_yard/object_tag.rb +21 -0
- data/lib/readme_yard/readme_tag.rb +41 -0
- data/lib/readme_yard/source_tag.rb +18 -0
- data/lib/readme_yard/version.rb +1 -1
- data/readme_yard.gemspec +1 -1
- metadata +11 -4
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e70847a5ff6d1679d77cc14a1f61154d1c43bd4f54087cca2cef1ecfa3288130
|
|
4
|
+
data.tar.gz: a78c652849586570a7fc15d8f327db4b57458bb230ec46c325ed6d207d7fcd9a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2d185d882b7be9a813841ec178a9ad1cf91c0b7ca48801ccf892500096cb5fb9295c5859bb17ad8356bf8c12d9a52741ef73e7ffe768f58377c5a92f18b567d0
|
|
7
|
+
data.tar.gz: 71205b0dce3be4c060af8b941a7f03fd47d7c40871c3941fbdefc572e214b2d8409eb4830a0dc5101538754e39c0ce14a433e10f18935360e4d12fb1f9fa54b7
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
## [Unreleased]
|
|
2
2
|
|
|
3
|
+
## 0.2.0 - 2021-08-08
|
|
4
|
+
|
|
5
|
+
- Add new readme tag types - `comment`, `source`, and `object`. Log warnings and raise errors when helpful. Update README. 51997f24d5209fd8f0e5e11511352f6457bb9dbe
|
|
6
|
+
|
|
3
7
|
## 0.1.2 - 2021-08-06
|
|
4
8
|
|
|
5
9
|
- Fix error message markdown parsing. 0f1c3fa4f39c6d7a1628f81e1ea41489b7021254
|
data/Gemfile.lock
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
PATH
|
|
2
2
|
remote: .
|
|
3
3
|
specs:
|
|
4
|
-
readme_yard (0.
|
|
4
|
+
readme_yard (0.2.0)
|
|
5
5
|
tty-markdown (~> 0.7)
|
|
6
|
-
yard-readme (~> 0.
|
|
6
|
+
yard-readme (~> 0.3)
|
|
7
7
|
|
|
8
8
|
GEM
|
|
9
9
|
remote: https://rubygems.org/
|
|
@@ -31,7 +31,7 @@ GEM
|
|
|
31
31
|
unicode-display_width (2.0.0)
|
|
32
32
|
unicode_utils (1.4.0)
|
|
33
33
|
yard (0.9.26)
|
|
34
|
-
yard-readme (0.
|
|
34
|
+
yard-readme (0.3.0)
|
|
35
35
|
yard (~> 0.9.26)
|
|
36
36
|
|
|
37
37
|
PLATFORMS
|
data/README.md
CHANGED
|
@@ -2,19 +2,45 @@
|
|
|
2
2
|
[](https://badge.fury.io/rb/readme_yard)
|
|
3
3
|
[](https://codeclimate.com/github/mattruzicka/readme_yard/maintainability)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
to see the template from which the README for this project was generated.
|
|
5
|
+
Build a better README with [YARD](https://yardoc.org),
|
|
6
|
+
one that summarizes and contextualizes the code and documentation,
|
|
7
|
+
without duplicating them.
|
|
9
8
|
|
|
9
|
+
This gem aims to minimize the effort needed to keep
|
|
10
|
+
your code, docs, and README useful, syncd, and correct.
|
|
11
|
+
|
|
12
|
+
For a glimpse of how it works, check out the [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
|
|
13
|
+
template from which this gem's README was generated.
|
|
10
14
|
If you're reading the README, that means this text is here
|
|
11
|
-
because `{@readme ReadmeYard}` is in
|
|
12
|
-
[README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
|
|
15
|
+
because `{@readme ReadmeYard}` is in the README_YARD file
|
|
13
16
|
and someone ran `readme build` at the command line.
|
|
14
17
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
Here's the [full documentation](https://rubydoc.info/github/mattruzicka/readme_yard).
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Table of Contents
|
|
24
|
+
- [Installation](#installation)
|
|
25
|
+
- [Getting Started](#getting-started)
|
|
26
|
+
- [Command Line Usage](#command-line-usage)
|
|
27
|
+
- [Tag Usage](#tag-usage)
|
|
28
|
+
- [Readme Tag](#readme-tag)
|
|
29
|
+
- [Readme YARD Tags](#readme-yard-tags)
|
|
30
|
+
- [Example Tag](#example-tag)
|
|
31
|
+
- [Contributing](#contributing)
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
Add [gem "readme_yard"](https://rubygems.org/gems/readme_yard) to your application's Gemfile and run `bundle install` or install it yourself with: `gem install readme_yard`
|
|
38
|
+
|
|
39
|
+
## Getting Started
|
|
40
|
+
|
|
41
|
+
Run `readme build` at the command line. That will create a README_YARD.md file if there isn’t one by copying your exisiting README.md file.
|
|
42
|
+
|
|
43
|
+
README_YARD.md is the template from which `readme build` generates the README. It augments your markdown with tagging capabilities as described in the section on [Tag Usage](#tag-usage).
|
|
18
44
|
|
|
19
45
|
---
|
|
20
46
|
|
|
@@ -26,85 +52,137 @@ _welcome_ to readme yard!
|
|
|
26
52
|
|
|
27
53
|
`readme doc` - Same as `readme build` + generates yard docs.
|
|
28
54
|
|
|
55
|
+
|
|
29
56
|
---
|
|
30
57
|
|
|
31
|
-
##
|
|
58
|
+
## Tag Usage
|
|
59
|
+
|
|
60
|
+
Readme Yard uses **README tags** and **YARD tags** in order to find, format, and embed Ruby source code inside README.md.
|
|
61
|
+
|
|
62
|
+
**README tags** live inside README_YARD.md.
|
|
63
|
+
|
|
64
|
+
**YARD tags** live inside Ruby source code.
|
|
32
65
|
|
|
33
|
-
|
|
66
|
+
When the Readme Yard build process encounters a tag in README_YARD.md, it searches the Ruby source code for its YARD tag counterpart, formats the output, and embeds it in the README file.
|
|
67
|
+
|
|
68
|
+
### Examples
|
|
69
|
+
|
|
70
|
+
This project's [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md) has `{@readme ReadmeYard.hello_world}` just below this paragraph, unless you're looking at the [README]((https://github.com/mattruzicka/readme_yard/blob/main/README.md)) where you should instead see a code example which was generated from running `readme build`.
|
|
71
|
+
|
|
72
|
+
```ruby
|
|
73
|
+
#
|
|
74
|
+
# @example
|
|
75
|
+
# ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
76
|
+
#
|
|
77
|
+
```
|
|
34
78
|
|
|
35
|
-
Next run `readme build` at the command line. This creates a README_YARD.md file if there isn’t one by copying the README file if it exists. It then parses README_YARD.md and writes the result to README.md.
|
|
36
79
|
|
|
37
|
-
|
|
80
|
+
The README tag tells Readme Yard to parse the `@readme` YARD tag located above the `hello_world` class method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
81
|
+
|
|
82
|
+
To use another "meta" example, `{@readme ReadmeYard}` is used at the top of this project's README_YARD.md file to generate the first few sentences of this README. `ReadmeYard` references the class located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
83
|
+
|
|
84
|
+
Last one, `{@readme ReadmeYard#command_line_usage}` is used to generate the "Command Line Usage" section above from the comments located above. `ReadmeYard#command_line_usage` references the instance method `command_line_usage` located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
38
85
|
|
|
39
86
|
---
|
|
40
87
|
|
|
41
|
-
##
|
|
88
|
+
## Readme Tag
|
|
89
|
+
|
|
90
|
+
**README Tag** syntax: `{@readme ObjectPath}`
|
|
42
91
|
|
|
43
|
-
|
|
92
|
+
**YARD Tag** syntax: `@example <name>`
|
|
44
93
|
|
|
45
|
-
|
|
94
|
+
By default, only the text nested under the @readme tag
|
|
95
|
+
will be embedded in the final output.
|
|
46
96
|
|
|
47
|
-
|
|
97
|
+
Different embed options are provided via the following
|
|
98
|
+
name options: `comment`, `source`, and `object`.
|
|
48
99
|
|
|
49
|
-
`{@readme ReadmeYard}` is used at the top of this project's README_YARD.md file to generate this README's title and description. `ReadmeYard` references the class located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
50
100
|
|
|
51
|
-
`{@readme ReadmeYard
|
|
101
|
+
The above two sentences were generated via `{@readme ReadmeYard::ReadmeTag}` in README_YARD.md and the @readme tag at the top of [ReadmeYard::ReadmeTag class](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb).
|
|
52
102
|
|
|
53
|
-
|
|
54
|
-
the class method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
103
|
+
## Readme YARD Tags
|
|
55
104
|
|
|
56
|
-
### @example
|
|
57
105
|
|
|
58
|
-
|
|
106
|
+
### Comment Tag
|
|
59
107
|
|
|
60
|
-
|
|
108
|
+
```@readme comment``` - Embeds the comment.
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
[This @readme comment YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/comment_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::CommentTag.format_tag_markdown}` is in README_YARD.md.
|
|
61
112
|
|
|
62
113
|
```ruby
|
|
63
|
-
|
|
114
|
+
#
|
|
115
|
+
# This comment is in the README because `@readme comment`
|
|
116
|
+
# is below, in the source code.
|
|
117
|
+
#
|
|
64
118
|
```
|
|
65
119
|
|
|
66
|
-
---
|
|
67
120
|
|
|
68
|
-
|
|
121
|
+
### Source Tag
|
|
69
122
|
|
|
70
|
-
|
|
123
|
+
```@readme source``` - Embeds the source.
|
|
71
124
|
|
|
72
|
-
I want a README that summarizes and contextualizes the code and documentation, without duplicating them, so as to make keeping it up-to-date easier. Laziness!
|
|
73
125
|
|
|
74
|
-
|
|
126
|
+
[This @readme source YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::SourceTag.format_tag_markdown}` is in README_YARD.md.
|
|
127
|
+
|
|
128
|
+
```ruby
|
|
129
|
+
def format_tag_markdown(yard_object, _tag)
|
|
130
|
+
ExampleTag.format_ruby(yard_object.source)
|
|
131
|
+
end
|
|
132
|
+
```
|
|
133
|
+
|
|
75
134
|
|
|
76
|
-
## Ideas
|
|
77
135
|
|
|
78
|
-
|
|
136
|
+
### Object Tag
|
|
79
137
|
|
|
80
|
-
|
|
138
|
+
```@readme object``` - Embeds the comment and source.
|
|
81
139
|
|
|
82
|
-
- `readme tags` - Prints usage and a list of all tags
|
|
83
140
|
|
|
84
|
-
|
|
141
|
+
[This @readme object YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::ObjectTag.format_tag_markdown}` is in README_YARD.md.
|
|
85
142
|
|
|
86
|
-
|
|
143
|
+
```ruby
|
|
144
|
+
#
|
|
145
|
+
# This method's comment and code is in the README because
|
|
146
|
+
# because `@readme object` is below, in the actual source code.
|
|
147
|
+
#
|
|
148
|
+
def format_tag_markdown(yard_object, _tag)
|
|
149
|
+
text = CommentTag.format_docstring_as_comment(yard_object)
|
|
150
|
+
text << "\n#{yard_object.source}"
|
|
151
|
+
ExampleTag.format_ruby(text)
|
|
152
|
+
end
|
|
153
|
+
```
|
|
87
154
|
|
|
88
|
-
- `readme tags <tag>` - Prints list of matching tag docstrings
|
|
89
155
|
|
|
90
|
-
- Improve linking. At the moment, there's lots of room for error when adding links in the YARD documentation.
|
|
91
156
|
|
|
92
|
-
|
|
157
|
+
---
|
|
93
158
|
|
|
94
|
-
|
|
159
|
+
## Example Tag
|
|
95
160
|
|
|
96
|
-
|
|
161
|
+
**README Tag** syntax: `{@example ObjectPath}`
|
|
97
162
|
|
|
98
|
-
|
|
163
|
+
**YARD Tag** example: `@example`
|
|
99
164
|
|
|
100
|
-
|
|
165
|
+
```ruby
|
|
166
|
+
#
|
|
167
|
+
# @example
|
|
168
|
+
# ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
169
|
+
#
|
|
170
|
+
```
|
|
101
171
|
|
|
102
|
-
- Integrate with the YARD server so that changes to documentation or README_YARD.md automatically regenerate the README
|
|
103
172
|
|
|
104
|
-
|
|
173
|
+
Given that the above comment is for the `hello_world` class method, the below example code is generated from placing `{@example ReadmeYard.hello_world}` in README_YARD.md.
|
|
174
|
+
|
|
175
|
+
```ruby
|
|
176
|
+
ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
177
|
+
```
|
|
178
|
+
|
|
105
179
|
|
|
106
180
|
---
|
|
107
181
|
|
|
108
182
|
## Contributing
|
|
109
183
|
|
|
110
184
|
Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.
|
|
185
|
+
|
|
186
|
+
Thanks for taking the time to think about me, the README.
|
|
187
|
+
|
|
188
|
+
🌿 🥏 🌱 ⚽
|
data/README_YARD.md
CHANGED
|
@@ -6,84 +6,117 @@
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Table of Contents
|
|
10
|
+
- [Installation](#installation)
|
|
11
|
+
- [Getting Started](#getting-started)
|
|
12
|
+
- [Command Line Usage](#command-line-usage)
|
|
13
|
+
- [Tag Usage](#tag-usage)
|
|
14
|
+
- [Readme Tag](#readme-tag)
|
|
15
|
+
- [Readme YARD Tags](#readme-yard-tags)
|
|
16
|
+
- [Example Tag](#example-tag)
|
|
17
|
+
- [Contributing](#contributing)
|
|
10
18
|
|
|
11
19
|
---
|
|
12
20
|
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
Add [gem "readme_yard"](https://rubygems.org/gems/readme_yard) to your application's Gemfile and run `bundle install` or install it yourself with: `gem install readme_yard`
|
|
24
|
+
|
|
13
25
|
## Getting Started
|
|
14
26
|
|
|
15
|
-
|
|
27
|
+
Run `readme build` at the command line. That will create a README_YARD.md file if there isn’t one by copying your exisiting README.md file.
|
|
16
28
|
|
|
17
|
-
|
|
29
|
+
README_YARD.md is the template from which `readme build` generates the README. It augments your markdown with tagging capabilities as described in the section on [Tag Usage](#tag-usage).
|
|
18
30
|
|
|
19
|
-
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
{@readme ReadmeYard#command_line_usage}
|
|
20
34
|
|
|
21
35
|
---
|
|
22
36
|
|
|
23
|
-
## Usage
|
|
37
|
+
## Tag Usage
|
|
24
38
|
|
|
25
|
-
|
|
39
|
+
Readme Yard uses **README tags** and **YARD tags** in order to find, format, and embed Ruby source code inside README.md.
|
|
26
40
|
|
|
27
|
-
|
|
41
|
+
**README tags** live inside README_YARD.md.
|
|
28
42
|
|
|
29
|
-
|
|
43
|
+
**YARD tags** live inside Ruby source code.
|
|
30
44
|
|
|
31
|
-
|
|
45
|
+
When the Readme Yard build process encounters a tag in README_YARD.md, it searches the Ruby source code for its YARD tag counterpart, formats the output, and embeds it in the README file.
|
|
32
46
|
|
|
33
|
-
|
|
47
|
+
### Examples
|
|
34
48
|
|
|
35
|
-
`{@readme ReadmeYard.hello_world}`
|
|
49
|
+
This project's [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md) has `{@readme ReadmeYard.hello_world}` just below this paragraph, unless you're looking at the [README]((https://github.com/mattruzicka/readme_yard/blob/main/README.md)) where you should instead see a code example which was generated from running `readme build`.
|
|
36
50
|
|
|
37
|
-
|
|
51
|
+
{@readme ReadmeYard.hello_world}
|
|
38
52
|
|
|
39
|
-
|
|
53
|
+
The README tag tells Readme Yard to parse the `@readme` YARD tag located above the `hello_world` class method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
40
54
|
|
|
41
|
-
|
|
55
|
+
To use another "meta" example, `{@readme ReadmeYard}` is used at the top of this project's README_YARD.md file to generate the first few sentences of this README. `ReadmeYard` references the class located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
42
56
|
|
|
43
|
-
{@
|
|
57
|
+
Last one, `{@readme ReadmeYard#command_line_usage}` is used to generate the "Command Line Usage" section above from the comments located above. `ReadmeYard#command_line_usage` references the instance method `command_line_usage` located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
44
58
|
|
|
45
59
|
---
|
|
46
60
|
|
|
47
|
-
##
|
|
61
|
+
## Readme Tag
|
|
48
62
|
|
|
49
|
-
|
|
63
|
+
**README Tag** syntax: `{@readme ObjectPath}`
|
|
50
64
|
|
|
51
|
-
|
|
65
|
+
**YARD Tag** syntax: `@example <name>`
|
|
52
66
|
|
|
53
|
-
|
|
67
|
+
{@readme ReadmeYard::ReadmeTag}
|
|
68
|
+
|
|
69
|
+
The above two sentences were generated via `{@readme ReadmeYard::ReadmeTag}` in README_YARD.md and the @readme tag at the top of [ReadmeYard::ReadmeTag class](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb).
|
|
54
70
|
|
|
55
|
-
##
|
|
71
|
+
## Readme YARD Tags
|
|
56
72
|
|
|
57
|
-
- Embed whole doc string if @readme tag is found, but there’s no text.
|
|
58
73
|
|
|
59
|
-
|
|
74
|
+
### Comment Tag
|
|
60
75
|
|
|
61
|
-
|
|
76
|
+
{@readme ReadmeYard::CommentTag}
|
|
62
77
|
|
|
63
|
-
|
|
78
|
+
[This @readme comment YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/comment_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::CommentTag.format_tag_markdown}` is in README_YARD.md.
|
|
64
79
|
|
|
65
|
-
|
|
80
|
+
{@readme ReadmeYard::CommentTag.format_tag_markdown}
|
|
66
81
|
|
|
67
|
-
|
|
82
|
+
### Source Tag
|
|
68
83
|
|
|
69
|
-
|
|
84
|
+
{@readme ReadmeYard::SourceTag}
|
|
70
85
|
|
|
71
|
-
|
|
86
|
+
[This @readme source YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::SourceTag.format_tag_markdown}` is in README_YARD.md.
|
|
72
87
|
|
|
73
|
-
|
|
88
|
+
{@readme ReadmeYard::SourceTag.format_tag_markdown}
|
|
74
89
|
|
|
75
|
-
- Follow @see links to find tags
|
|
76
90
|
|
|
77
|
-
|
|
91
|
+
### Object Tag
|
|
78
92
|
|
|
79
|
-
|
|
93
|
+
{@readme ReadmeYard::ObjectTag}
|
|
80
94
|
|
|
81
|
-
|
|
95
|
+
[This @readme object YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::ObjectTag.format_tag_markdown}` is in README_YARD.md.
|
|
96
|
+
|
|
97
|
+
{@readme ReadmeYard::ObjectTag.format_tag_markdown}
|
|
82
98
|
|
|
83
|
-
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Example Tag
|
|
103
|
+
|
|
104
|
+
**README Tag** syntax: `{@example ObjectPath}`
|
|
105
|
+
|
|
106
|
+
**YARD Tag** example: `@example`
|
|
107
|
+
|
|
108
|
+
{@readme ReadmeYard.hello_world}
|
|
109
|
+
|
|
110
|
+
Given that the above comment is for the `hello_world` class method, the below example code is generated from placing `{@example ReadmeYard.hello_world}` in README_YARD.md.
|
|
111
|
+
|
|
112
|
+
{@example ReadmeYard.hello_world}
|
|
84
113
|
|
|
85
114
|
---
|
|
86
115
|
|
|
87
116
|
## Contributing
|
|
88
117
|
|
|
89
118
|
Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.
|
|
119
|
+
|
|
120
|
+
Thanks for taking the time to think about me, the README.
|
|
121
|
+
|
|
122
|
+
🌿 🥏 🌱 ⚽
|
data/lib/readme_yard.rb
CHANGED
|
@@ -2,44 +2,39 @@
|
|
|
2
2
|
|
|
3
3
|
require "yard-readme"
|
|
4
4
|
require_relative "readme_yard/version"
|
|
5
|
+
require_relative "readme_yard/error"
|
|
6
|
+
require_relative "readme_yard/logger"
|
|
7
|
+
require_relative "readme_yard/readme_tag"
|
|
8
|
+
require_relative "readme_yard/example_tag"
|
|
9
|
+
require_relative "readme_yard/comment_tag"
|
|
10
|
+
require_relative "readme_yard/source_tag"
|
|
11
|
+
require_relative "readme_yard/object_tag"
|
|
12
|
+
|
|
13
|
+
YARDReadme::DocstringParser.readme_tag_names = %w[comment source object]
|
|
5
14
|
|
|
6
15
|
#
|
|
7
16
|
# @readme
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
#
|
|
11
|
-
#
|
|
17
|
+
# Build a better README with [YARD](https://yardoc.org),
|
|
18
|
+
# one that summarizes and contextualizes the code and documentation,
|
|
19
|
+
# without duplicating them.
|
|
20
|
+
#
|
|
21
|
+
# This gem aims to minimize the effort needed to keep
|
|
22
|
+
# your code, docs, and README useful, syncd, and correct.
|
|
12
23
|
#
|
|
24
|
+
# For a glimpse of how it works, check out the [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
|
|
25
|
+
# template from which this gem's README was generated.
|
|
13
26
|
# If you're reading the README, that means this text is here
|
|
14
|
-
# because `{@readme ReadmeYard}` is in
|
|
15
|
-
# [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
|
|
27
|
+
# because `{@readme ReadmeYard}` is in the README_YARD file
|
|
16
28
|
# and someone ran `readme build` at the command line.
|
|
17
29
|
#
|
|
18
|
-
#
|
|
19
|
-
# [documentation](https://rubydoc.info/github/mattruzicka/readme_yard),
|
|
20
|
-
# _welcome_ to readme yard!
|
|
30
|
+
# Here's the [full documentation](https://rubydoc.info/github/mattruzicka/readme_yard).
|
|
21
31
|
#
|
|
22
32
|
class ReadmeYard
|
|
23
|
-
class Error < StandardError
|
|
24
|
-
class << self
|
|
25
|
-
# TODO: Look for instance method with same name if
|
|
26
|
-
# class method and vise versa to give a more helpful error.
|
|
27
|
-
# Also, look for the object path in other scopes.
|
|
28
|
-
def object_not_found(tag_name, object_path)
|
|
29
|
-
new("`#{object_path}` could not be found. Perhaps" \
|
|
30
|
-
" the `@#{tag_name}` tag was moved, mispelled," \
|
|
31
|
-
" or the `.yardopts` YARD file is missing the file path.")
|
|
32
|
-
end
|
|
33
|
-
end
|
|
34
|
-
end
|
|
35
|
-
|
|
36
33
|
#
|
|
37
|
-
# @readme
|
|
38
|
-
# This object only exists so that you can read this in the README. `ReadmeYard.hello_world` references
|
|
39
|
-
# the class method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
|
|
34
|
+
# @readme comment
|
|
40
35
|
#
|
|
41
36
|
# @example
|
|
42
|
-
# ReadmeYard.hello_world
|
|
37
|
+
# ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
43
38
|
#
|
|
44
39
|
def self.hello_world
|
|
45
40
|
"Hello 🌎 🌍 🌏"
|
|
@@ -63,6 +58,16 @@ class ReadmeYard
|
|
|
63
58
|
puts TTY::Markdown.parse(e.message)
|
|
64
59
|
end
|
|
65
60
|
|
|
61
|
+
TAG_CLASS_LOOKUP = { "readme" => ReadmeTag,
|
|
62
|
+
"example" => ExampleTag,
|
|
63
|
+
"source" => SourceTag,
|
|
64
|
+
"comment" => CommentTag,
|
|
65
|
+
"object" => ObjectTag }.freeze
|
|
66
|
+
|
|
67
|
+
def self.lookup_tag_class(tag_name)
|
|
68
|
+
TAG_CLASS_LOOKUP[tag_name]
|
|
69
|
+
end
|
|
70
|
+
|
|
66
71
|
def initialize
|
|
67
72
|
@readme_path = "./README.md"
|
|
68
73
|
@readme_yard_path = "./README_YARD.md"
|
|
@@ -85,8 +90,8 @@ class ReadmeYard
|
|
|
85
90
|
def command_line_usage
|
|
86
91
|
yard_parse_this_file
|
|
87
92
|
yard_object = YARD::Registry.at("#{self.class.name}##{__method__}")
|
|
88
|
-
|
|
89
|
-
"\n#{
|
|
93
|
+
yard_tags = yard_object.tags(:readme)
|
|
94
|
+
"\n#{ReadmeTag.format_markdown(yard_object, yard_tags)}\n\n"
|
|
90
95
|
end
|
|
91
96
|
|
|
92
97
|
#
|
|
@@ -100,6 +105,7 @@ class ReadmeYard
|
|
|
100
105
|
# `-q` silence yardoc output statements
|
|
101
106
|
#
|
|
102
107
|
def build(options: "-nq")
|
|
108
|
+
find_or_upsert_yardopts
|
|
103
109
|
run_yardoc(options: options)
|
|
104
110
|
File.write(readme_path, gsub_tags!(readme_yard_md))
|
|
105
111
|
end
|
|
@@ -107,12 +113,12 @@ class ReadmeYard
|
|
|
107
113
|
#
|
|
108
114
|
# @readme Same as "build" + generates yard docs.
|
|
109
115
|
#
|
|
110
|
-
def doc(options: "-q
|
|
111
|
-
build(options: options || "-q
|
|
116
|
+
def doc(options: "-q")
|
|
117
|
+
build(options: options || "-q")
|
|
112
118
|
end
|
|
113
119
|
|
|
114
120
|
def run_yardoc(options: "-nq")
|
|
115
|
-
YARD::CLI::Yardoc.run(
|
|
121
|
+
YARD::CLI::Yardoc.run(options || "-nq")
|
|
116
122
|
end
|
|
117
123
|
|
|
118
124
|
private
|
|
@@ -130,22 +136,6 @@ class ReadmeYard
|
|
|
130
136
|
new_readme_yard_md
|
|
131
137
|
end
|
|
132
138
|
|
|
133
|
-
#
|
|
134
|
-
# This method adds the below paragraph to a project's
|
|
135
|
-
# README file, if it doesn't already have one when running
|
|
136
|
-
# `readme build` for the first time.
|
|
137
|
-
#
|
|
138
|
-
# @readme
|
|
139
|
-
# This is a quick example of using a readme tag in README_YARD.md
|
|
140
|
-
#
|
|
141
|
-
# > {@readme ReadmeYard#default_readme_yard_md}
|
|
142
|
-
#
|
|
143
|
-
# to copy a `@readme` comment from
|
|
144
|
-
# [source code](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb)
|
|
145
|
-
# and paste it into the README file.
|
|
146
|
-
#
|
|
147
|
-
# 🌱 ⚽
|
|
148
|
-
#
|
|
149
139
|
def default_readme_yard_md
|
|
150
140
|
yard_parse_this_file
|
|
151
141
|
+"Welcome to the README_YARD 🌿 🥏\n\n" \
|
|
@@ -154,24 +144,70 @@ class ReadmeYard
|
|
|
154
144
|
" for usage.\n\n{@readme ReadmeYard#default_readme_yard_md}"
|
|
155
145
|
end
|
|
156
146
|
|
|
147
|
+
YARDOPTS_FILE = ".yardopts"
|
|
148
|
+
|
|
149
|
+
def find_or_upsert_yardopts
|
|
150
|
+
File.exist?(YARDOPTS_FILE) ? update_yardopts_file : create_yardopts_file
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
def update_yardopts_file
|
|
154
|
+
text = File.read(YARDOPTS_FILE)
|
|
155
|
+
text_addition = build_yardopts_text_addition(text)
|
|
156
|
+
File.open(YARDOPTS_FILE, "a") { |f| f.write(text_addition) } if text_addition
|
|
157
|
+
end
|
|
158
|
+
|
|
159
|
+
def build_yardopts_text_addition(yardopts_text)
|
|
160
|
+
return if yardopts_text.match?(/\s*--plugin\s+readme\W/)
|
|
161
|
+
|
|
162
|
+
readme_plugin_opts = default_readme_plugin_opts(yardopts_text)
|
|
163
|
+
case yardopts_text
|
|
164
|
+
when /\s*--markup\s+markdown/, /\s*-m\s+markdown/
|
|
165
|
+
readme_plugin_opts
|
|
166
|
+
when /\s*--markup\s/, /\s*-m\s/
|
|
167
|
+
warn_about_supported_markdown
|
|
168
|
+
readme_plugin_opts
|
|
169
|
+
else
|
|
170
|
+
readme_plugin_opts << "--markup markdown\n"
|
|
171
|
+
end
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
def default_readme_plugin_opts(yardopts_text)
|
|
175
|
+
readme_opts = +""
|
|
176
|
+
readme_opts << "\n" unless yardopts_text.lines.last.include?("\n")
|
|
177
|
+
readme_opts << "--plugin readme\n"
|
|
178
|
+
end
|
|
179
|
+
|
|
180
|
+
def create_yardopts_file
|
|
181
|
+
File.write(YARDOPTS_FILE, "--plugin readme\n--markup markdown\n")
|
|
182
|
+
end
|
|
183
|
+
|
|
157
184
|
def gsub_tags!(markdown)
|
|
158
|
-
markdown.gsub!(/([^`]|^)(\{@\w+\s.+\})/) { |string|
|
|
185
|
+
markdown.gsub!(/([^`]|^)(\{@\w+\s.+\})/) { |string| format_tag_markdown(string) }
|
|
159
186
|
markdown
|
|
160
187
|
end
|
|
161
188
|
|
|
162
|
-
def
|
|
189
|
+
def format_tag_markdown(string)
|
|
163
190
|
first_char = string[0]
|
|
164
191
|
return string if first_char == "`"
|
|
165
192
|
|
|
166
193
|
tag_name = extract_tag_name(string)
|
|
167
194
|
object_path = extract_object_path(string)
|
|
168
|
-
|
|
169
|
-
raise Error.
|
|
195
|
+
yard_object = YARD::Registry.at(object_path)
|
|
196
|
+
raise Error.object_not_found(object_path, tag_name) unless yard_object
|
|
170
197
|
|
|
171
|
-
|
|
172
|
-
|
|
198
|
+
yard_tags_markdown = format_yard_tags_markdown(yard_object, tag_name, string)
|
|
199
|
+
"#{first_char if first_char != "{"}#{yard_tags_markdown}"
|
|
200
|
+
end
|
|
173
201
|
|
|
174
|
-
|
|
202
|
+
def format_yard_tags_markdown(yard_object, tag_name, string)
|
|
203
|
+
yard_tags = yard_object.tags(tag_name)
|
|
204
|
+
if yard_tags.empty?
|
|
205
|
+
warn_about_yard_tags_not_found(yard_object, tag_name)
|
|
206
|
+
string
|
|
207
|
+
else
|
|
208
|
+
tag_class = self.class.lookup_tag_class(tag_name)
|
|
209
|
+
tag_class.format_markdown(yard_object, yard_tags)
|
|
210
|
+
end
|
|
175
211
|
end
|
|
176
212
|
|
|
177
213
|
def extract_tag_name(tag_string)
|
|
@@ -182,17 +218,18 @@ class ReadmeYard
|
|
|
182
218
|
tag_string.match(/\s(\b.+)}/).captures.first
|
|
183
219
|
end
|
|
184
220
|
|
|
185
|
-
def format_readme_tags(tags)
|
|
186
|
-
tags.map(&:text).join
|
|
187
|
-
end
|
|
188
|
-
|
|
189
|
-
def format_example_tags(tags)
|
|
190
|
-
tags.map { |tag| "```ruby\n#{tag.text}\n```" }.join("\n")
|
|
191
|
-
end
|
|
192
|
-
|
|
193
221
|
def yard_parse_this_file
|
|
194
222
|
gem_spec = Gem::Specification.find_by_name("readme_yard")
|
|
195
223
|
current_file_path = File.join(gem_spec.full_gem_path, "lib", "readme_yard.rb")
|
|
196
224
|
YARD.parse(current_file_path)
|
|
197
225
|
end
|
|
226
|
+
|
|
227
|
+
def warn_about_supported_markdown
|
|
228
|
+
Logger.warn "\n*Readme Yard* works best with markdown." \
|
|
229
|
+
"\nConsider adding `--markup markdown` to your `.yardopts` file.\n\n"
|
|
230
|
+
end
|
|
231
|
+
|
|
232
|
+
def warn_about_yard_tags_not_found(yard_object, tag_name)
|
|
233
|
+
Logger.warn "The `@#{tag_name}` *Readme Yard* tag is missing from #{yard_object}."
|
|
234
|
+
end
|
|
198
235
|
end
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
class ReadmeYard
|
|
2
|
+
#
|
|
3
|
+
# @readme
|
|
4
|
+
# ```@readme comment``` - Embeds the comment.
|
|
5
|
+
#
|
|
6
|
+
class CommentTag
|
|
7
|
+
class << self
|
|
8
|
+
#
|
|
9
|
+
# This comment is in the README because `@readme comment`
|
|
10
|
+
# is below, in the source code.
|
|
11
|
+
#
|
|
12
|
+
# @readme comment
|
|
13
|
+
#
|
|
14
|
+
def format_tag_markdown(yard_object, _tag)
|
|
15
|
+
comment = format_docstring_as_comment(yard_object)
|
|
16
|
+
ExampleTag.format_ruby(comment)
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
#
|
|
20
|
+
# @see https://rubydoc.info/gems/yard/YARD%2FDocstring:to_raw
|
|
21
|
+
#
|
|
22
|
+
def format_docstring_as_comment(yard_object)
|
|
23
|
+
comment = +""
|
|
24
|
+
docstring = yard_object.docstring.all
|
|
25
|
+
docstring.gsub!(named_readme_tag_regex, "")
|
|
26
|
+
docstring.lines.each do |line|
|
|
27
|
+
comment << "#"
|
|
28
|
+
comment << " " unless line[0] == "\n"
|
|
29
|
+
comment << line
|
|
30
|
+
end
|
|
31
|
+
last_line = yard_object.docstring.all.lines.last
|
|
32
|
+
comment << "#" if last_line.match?(/\n$/)
|
|
33
|
+
comment
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
def named_readme_tag_regex
|
|
37
|
+
@named_readme_tag_regex ||= /(\n|^)@readme\s(#{YARDReadme::DocstringParser.readme_tag_names.join("|")})\n/
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
end
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
class ReadmeYard
|
|
2
|
+
class Error < StandardError
|
|
3
|
+
class << self
|
|
4
|
+
#
|
|
5
|
+
# @todo
|
|
6
|
+
# Look for instance method with same name if
|
|
7
|
+
# class method and vise versa to give a more helpful error.
|
|
8
|
+
# Look for the object path in other scopes.
|
|
9
|
+
#
|
|
10
|
+
def object_not_found(object_path, tag_name)
|
|
11
|
+
new("*Readme Yard* could not find `#{object_path}`. Perhaps" \
|
|
12
|
+
" the `@#{tag_name}` tag was moved, mispelled," \
|
|
13
|
+
" or the `.yardopts` YARD file is missing the file path.")
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
end
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
class ReadmeYard
|
|
2
|
+
class ExampleTag
|
|
3
|
+
class << self
|
|
4
|
+
def format_markdown(yard_object, yard_tags)
|
|
5
|
+
yard_tags.map { |tag| format_tag_markdown(yard_object, tag) }.join("\n")
|
|
6
|
+
end
|
|
7
|
+
|
|
8
|
+
def format_tag_markdown(yard_object, tag)
|
|
9
|
+
text = tag.text.empty? ? yard_object.source : tag.text
|
|
10
|
+
format_ruby(text)
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
def format_ruby(text)
|
|
14
|
+
"```ruby\n#{text}\n```\n"
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
end
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
class ReadmeYard
|
|
2
|
+
#
|
|
3
|
+
# @readme
|
|
4
|
+
# ```@readme object``` - Embeds the comment and source.
|
|
5
|
+
#
|
|
6
|
+
class ObjectTag
|
|
7
|
+
class << self
|
|
8
|
+
#
|
|
9
|
+
# This method's comment and code is in the README because
|
|
10
|
+
# because `@readme object` is below, in the actual source code.
|
|
11
|
+
#
|
|
12
|
+
# @readme object
|
|
13
|
+
#
|
|
14
|
+
def format_tag_markdown(yard_object, _tag)
|
|
15
|
+
text = CommentTag.format_docstring_as_comment(yard_object)
|
|
16
|
+
text << "\n#{yard_object.source}"
|
|
17
|
+
ExampleTag.format_ruby(text)
|
|
18
|
+
end
|
|
19
|
+
end
|
|
20
|
+
end
|
|
21
|
+
end
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
class ReadmeYard
|
|
2
|
+
#
|
|
3
|
+
# @readme
|
|
4
|
+
# By default, only the text nested under the @readme tag
|
|
5
|
+
# will be embedded in the final output.
|
|
6
|
+
#
|
|
7
|
+
# Different embed options are provided via the following
|
|
8
|
+
# name options: `comment`, `source`, and `object`.
|
|
9
|
+
#
|
|
10
|
+
# @see ReadmeYard::CommentTag
|
|
11
|
+
# @see ReadmeYard::SourceTag
|
|
12
|
+
# @see ReadmeYard::ObjectTag
|
|
13
|
+
#
|
|
14
|
+
class ReadmeTag
|
|
15
|
+
class << self
|
|
16
|
+
def format_markdown(yard_object, yard_tags)
|
|
17
|
+
md = +""
|
|
18
|
+
yard_tags.each do |tag|
|
|
19
|
+
res = format_yard_tag(yard_object, tag)
|
|
20
|
+
md << res if res
|
|
21
|
+
end
|
|
22
|
+
md
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
def format_tag_markdown(_yard_object, tag)
|
|
26
|
+
"#{tag.text}\n"
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
private
|
|
30
|
+
|
|
31
|
+
def format_yard_tag(yard_object, tag)
|
|
32
|
+
if tag.name && !tag.name.empty?
|
|
33
|
+
tag_class = ReadmeYard.lookup_tag_class(tag.name)
|
|
34
|
+
tag_class&.format_tag_markdown(yard_object, tag)
|
|
35
|
+
elsif tag.text && !tag.text.empty?
|
|
36
|
+
format_tag_markdown(yard_object, tag)
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
end
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
class ReadmeYard
|
|
2
|
+
#
|
|
3
|
+
# @readme
|
|
4
|
+
# ```@readme source``` - Embeds the source.
|
|
5
|
+
#
|
|
6
|
+
class SourceTag
|
|
7
|
+
class << self
|
|
8
|
+
#
|
|
9
|
+
# The following tag embeds this method's source.
|
|
10
|
+
#
|
|
11
|
+
# @readme source
|
|
12
|
+
#
|
|
13
|
+
def format_tag_markdown(yard_object, _tag)
|
|
14
|
+
ExampleTag.format_ruby(yard_object.source)
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
end
|
data/lib/readme_yard/version.rb
CHANGED
data/readme_yard.gemspec
CHANGED
|
@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
|
|
|
27
27
|
|
|
28
28
|
# Uncomment to register a new dependency of your gem
|
|
29
29
|
spec.add_dependency "tty-markdown", "~> 0.7"
|
|
30
|
-
spec.add_dependency "yard-readme", "~> 0.
|
|
30
|
+
spec.add_dependency "yard-readme", "~> 0.3"
|
|
31
31
|
|
|
32
32
|
# For more information and examples about making a new gem, checkout our
|
|
33
33
|
# guide at: https://bundler.io/guides/creating_gem.html
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: readme_yard
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.2.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Matt Ruzicka
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2021-08-
|
|
11
|
+
date: 2021-08-08 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: tty-markdown
|
|
@@ -30,14 +30,14 @@ dependencies:
|
|
|
30
30
|
requirements:
|
|
31
31
|
- - "~>"
|
|
32
32
|
- !ruby/object:Gem::Version
|
|
33
|
-
version: '0.
|
|
33
|
+
version: '0.3'
|
|
34
34
|
type: :runtime
|
|
35
35
|
prerelease: false
|
|
36
36
|
version_requirements: !ruby/object:Gem::Requirement
|
|
37
37
|
requirements:
|
|
38
38
|
- - "~>"
|
|
39
39
|
- !ruby/object:Gem::Version
|
|
40
|
-
version: '0.
|
|
40
|
+
version: '0.3'
|
|
41
41
|
description:
|
|
42
42
|
email:
|
|
43
43
|
executables:
|
|
@@ -59,6 +59,13 @@ files:
|
|
|
59
59
|
- bin/readme
|
|
60
60
|
- bin/setup
|
|
61
61
|
- lib/readme_yard.rb
|
|
62
|
+
- lib/readme_yard/comment_tag.rb
|
|
63
|
+
- lib/readme_yard/error.rb
|
|
64
|
+
- lib/readme_yard/example_tag.rb
|
|
65
|
+
- lib/readme_yard/logger.rb
|
|
66
|
+
- lib/readme_yard/object_tag.rb
|
|
67
|
+
- lib/readme_yard/readme_tag.rb
|
|
68
|
+
- lib/readme_yard/source_tag.rb
|
|
62
69
|
- lib/readme_yard/version.rb
|
|
63
70
|
- readme_yard.gemspec
|
|
64
71
|
homepage: https://github.com/mattruzicka/readme_yard
|