readme_yard 0.1.2 → 0.2.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/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
|