readme_yard 0.2.0 → 0.4.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/.rubocop.yml +1 -1
- data/.yardopts +1 -0
- data/CHANGELOG.md +18 -1
- data/Gemfile +3 -0
- data/Gemfile.lock +67 -15
- data/README.md +165 -55
- data/README_YARD.md +109 -37
- data/bin/readme +2 -2
- data/lib/readme_yard/code_tag.rb +28 -0
- data/lib/readme_yard/comment_tag.rb +14 -5
- data/lib/readme_yard/error.rb +2 -0
- data/lib/readme_yard/example_tag.rb +21 -3
- data/lib/readme_yard/logger.rb +12 -1
- data/lib/readme_yard/readme_tag.rb +15 -11
- data/lib/readme_yard/source_tag.rb +16 -4
- data/lib/readme_yard/string_tag.rb +86 -0
- data/lib/readme_yard/tag_registry.rb +21 -0
- data/lib/readme_yard/value_tag.rb +31 -0
- data/lib/readme_yard/version.rb +1 -1
- data/lib/readme_yard/yard_opts_manager.rb +49 -0
- data/lib/readme_yard.rb +60 -95
- data/readme_yard.gemspec +8 -3
- metadata +53 -12
- data/lib/readme_yard/object_tag.rb +0 -21
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 75f0e416616f2e2e893d7a64da99c4fd364d4624309d60cf5fb1cee1f7f8d824
|
|
4
|
+
data.tar.gz: 2a7230288228a5a8fdf2d9198ed1a571d6275529c739b24ef8617765e38757dc
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 9982537f18b8205ca25ea49f95d3affcee71d4d228c5c3b93612d7cb7fdbb26e2f4224b64b20adcad438d727392eeb24d1ffe801b296970cdbb336f41ed6b215
|
|
7
|
+
data.tar.gz: 2502d485c42940b1e25e8b8fe2ed8076d0f913c4e69bcdc8534c676031f73f790d67efa074bfb54a45ddf50d76c71dba6cf138feb28e48cece33de2f5139a7e1
|
data/.rubocop.yml
CHANGED
data/.yardopts
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -1,4 +1,21 @@
|
|
|
1
|
-
##
|
|
1
|
+
## 0.4.0 - 2025-05-05
|
|
2
|
+
|
|
3
|
+
- Added colored diff output when readme build/yard commands finish, showing changes to README.md using the Diffy gem
|
|
4
|
+
- Changed default options for `readme yard` command to display YARD doc stats
|
|
5
|
+
- Added code version display in README.md showing current version from ReadmeYard::VERSION
|
|
6
|
+
|
|
7
|
+
## 0.3.0 - 2025-05-04
|
|
8
|
+
|
|
9
|
+
- Update dependencies: upgraded yard-readme to 0.5.0, Ruby requirement to >= 3.0
|
|
10
|
+
- Add TagRegistry class to centralize tag management
|
|
11
|
+
- Update bundler and various gem dependencies
|
|
12
|
+
- Improve command-line argument handling in the readme executable
|
|
13
|
+
- Extract YardOptsManager to improve code organization
|
|
14
|
+
- Rename ObjectTag to SourceTag and rename old SourceTag to CodeTag
|
|
15
|
+
- Add new ValueTag and StringTag
|
|
16
|
+
- Add standalone tag support: enable embedding yard content in README without yard tags in the source code
|
|
17
|
+
- Rename format methods for consistency
|
|
18
|
+
- Rename `readme doc` command to `readme yard` for clarity and improved memorability
|
|
2
19
|
|
|
3
20
|
## 0.2.0 - 2021-08-08
|
|
4
21
|
|
data/Gemfile
CHANGED
data/Gemfile.lock
CHANGED
|
@@ -1,44 +1,96 @@
|
|
|
1
1
|
PATH
|
|
2
2
|
remote: .
|
|
3
3
|
specs:
|
|
4
|
-
readme_yard (0.
|
|
4
|
+
readme_yard (0.4.0)
|
|
5
|
+
diffy (~> 3.4)
|
|
5
6
|
tty-markdown (~> 0.7)
|
|
6
|
-
yard
|
|
7
|
+
yard (~> 0.9)
|
|
8
|
+
yard-readme (~> 0.5)
|
|
7
9
|
|
|
8
10
|
GEM
|
|
9
11
|
remote: https://rubygems.org/
|
|
10
12
|
specs:
|
|
11
|
-
|
|
12
|
-
|
|
13
|
+
ast (2.4.3)
|
|
14
|
+
date (3.4.1)
|
|
15
|
+
debug (1.10.0)
|
|
16
|
+
irb (~> 1.10)
|
|
17
|
+
reline (>= 0.3.8)
|
|
18
|
+
diffy (3.4.3)
|
|
19
|
+
io-console (0.8.0)
|
|
20
|
+
irb (1.15.2)
|
|
21
|
+
pp (>= 0.6.0)
|
|
22
|
+
rdoc (>= 4.0.0)
|
|
23
|
+
reline (>= 0.4.2)
|
|
24
|
+
json (2.11.3)
|
|
25
|
+
kramdown (2.5.1)
|
|
26
|
+
rexml (>= 3.3.9)
|
|
27
|
+
language_server-protocol (3.17.0.4)
|
|
28
|
+
lint_roller (1.1.0)
|
|
29
|
+
parallel (1.27.0)
|
|
30
|
+
parser (3.3.8.0)
|
|
31
|
+
ast (~> 2.4.1)
|
|
32
|
+
racc
|
|
13
33
|
pastel (0.8.0)
|
|
14
34
|
tty-color (~> 0.5)
|
|
15
|
-
|
|
16
|
-
|
|
35
|
+
pp (0.6.2)
|
|
36
|
+
prettyprint
|
|
37
|
+
prettyprint (0.2.0)
|
|
38
|
+
prism (1.4.0)
|
|
39
|
+
psych (5.2.4)
|
|
40
|
+
date
|
|
41
|
+
stringio
|
|
42
|
+
racc (1.8.1)
|
|
43
|
+
rainbow (3.1.1)
|
|
44
|
+
rdoc (6.13.1)
|
|
45
|
+
psych (>= 4.0.0)
|
|
46
|
+
regexp_parser (2.10.0)
|
|
47
|
+
reline (0.6.1)
|
|
48
|
+
io-console (~> 0.5)
|
|
49
|
+
rexml (3.4.1)
|
|
50
|
+
rouge (4.5.2)
|
|
51
|
+
rubocop (1.75.5)
|
|
52
|
+
json (~> 2.3)
|
|
53
|
+
language_server-protocol (~> 3.17.0.2)
|
|
54
|
+
lint_roller (~> 1.1.0)
|
|
55
|
+
parallel (~> 1.10)
|
|
56
|
+
parser (>= 3.3.0.2)
|
|
57
|
+
rainbow (>= 2.2.2, < 4.0)
|
|
58
|
+
regexp_parser (>= 2.9.3, < 3.0)
|
|
59
|
+
rubocop-ast (>= 1.44.0, < 2.0)
|
|
60
|
+
ruby-progressbar (~> 1.7)
|
|
61
|
+
unicode-display_width (>= 2.4.0, < 4.0)
|
|
62
|
+
rubocop-ast (1.44.1)
|
|
63
|
+
parser (>= 3.3.7.2)
|
|
64
|
+
prism (~> 1.4)
|
|
65
|
+
ruby-progressbar (1.13.0)
|
|
66
|
+
stringio (3.1.7)
|
|
17
67
|
strings (0.2.1)
|
|
18
68
|
strings-ansi (~> 0.2)
|
|
19
69
|
unicode-display_width (>= 1.5, < 3.0)
|
|
20
70
|
unicode_utils (~> 1.4)
|
|
21
71
|
strings-ansi (0.2.0)
|
|
22
72
|
tty-color (0.6.0)
|
|
23
|
-
tty-markdown (0.7.
|
|
73
|
+
tty-markdown (0.7.2)
|
|
24
74
|
kramdown (>= 1.16.2, < 3.0)
|
|
25
75
|
pastel (~> 0.8)
|
|
26
|
-
rouge (
|
|
76
|
+
rouge (>= 3.14, < 5.0)
|
|
27
77
|
strings (~> 0.2.0)
|
|
28
78
|
tty-color (~> 0.5)
|
|
29
79
|
tty-screen (~> 0.8)
|
|
30
|
-
tty-screen (0.8.
|
|
31
|
-
unicode-display_width (2.
|
|
80
|
+
tty-screen (0.8.2)
|
|
81
|
+
unicode-display_width (2.6.0)
|
|
32
82
|
unicode_utils (1.4.0)
|
|
33
|
-
yard (0.9.
|
|
34
|
-
yard-readme (0.
|
|
35
|
-
yard (~> 0.9.26)
|
|
83
|
+
yard (0.9.37)
|
|
84
|
+
yard-readme (0.6.0)
|
|
36
85
|
|
|
37
86
|
PLATFORMS
|
|
38
|
-
arm64-darwin-
|
|
87
|
+
arm64-darwin-24
|
|
39
88
|
|
|
40
89
|
DEPENDENCIES
|
|
90
|
+
debug
|
|
91
|
+
irb
|
|
41
92
|
readme_yard!
|
|
93
|
+
rubocop (~> 1.75, >= 1.75.4)
|
|
42
94
|
|
|
43
95
|
BUNDLED WITH
|
|
44
|
-
2.
|
|
96
|
+
2.6.8
|
data/README.md
CHANGED
|
@@ -1,23 +1,37 @@
|
|
|
1
1
|
# Readme Yard 🌿
|
|
2
2
|
[](https://badge.fury.io/rb/readme_yard)
|
|
3
|
-
[](https://codeclimate.com/github/mattruzicka/readme_yard/maintainability)
|
|
4
3
|
|
|
5
|
-
|
|
6
|
-
one that summarizes and contextualizes the code and documentation,
|
|
7
|
-
without duplicating them.
|
|
4
|
+
**Code Version: 0.4.0**
|
|
8
5
|
|
|
9
|
-
|
|
10
|
-
|
|
6
|
+
Build a better README with [YARD](https://yardoc.org)
|
|
7
|
+
by generating it straight from the source.
|
|
11
8
|
|
|
12
|
-
|
|
13
|
-
|
|
9
|
+
This gem aims to minimize the effort needed to keep your
|
|
10
|
+
README, documentation, and source code synced, useful,
|
|
11
|
+
and correct. Among its features, it introduces the @readme tag
|
|
12
|
+
that enables you to embed code comments directly into README sections,
|
|
13
|
+
eliminating redundancy and keeping documentation consistent
|
|
14
|
+
across your codebase and project README.
|
|
15
|
+
|
|
16
|
+
Look at the [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
|
|
17
|
+
template for this project to see how it works.
|
|
14
18
|
If you're reading the README, that means this text is here
|
|
15
|
-
because `{@readme ReadmeYard}` is in
|
|
16
|
-
and
|
|
19
|
+
because the custom `{@readme ReadmeYard}` markdown tag is in
|
|
20
|
+
README_YARD.md and `readme build` was run at the command line.
|
|
17
21
|
|
|
18
22
|
Here's the [full documentation](https://rubydoc.info/github/mattruzicka/readme_yard).
|
|
19
23
|
|
|
20
24
|
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
⚠️ **Generated file warning** – Edit README_YARD.md, not README.md. Changes to README.md will be lost when running `readme build`.
|
|
28
|
+
|
|
29
|
+
### Future Work
|
|
30
|
+
- Implement safeguards to prevent accidental edits to README.md
|
|
31
|
+
- Support bidirectional editing through git integration
|
|
32
|
+
|
|
33
|
+
[PRs are welcome](#contributing) for these improvements.
|
|
34
|
+
|
|
21
35
|
---
|
|
22
36
|
|
|
23
37
|
## Table of Contents
|
|
@@ -26,7 +40,7 @@ Here's the [full documentation](https://rubydoc.info/github/mattruzicka/readme_y
|
|
|
26
40
|
- [Command Line Usage](#command-line-usage)
|
|
27
41
|
- [Tag Usage](#tag-usage)
|
|
28
42
|
- [Readme Tag](#readme-tag)
|
|
29
|
-
- [
|
|
43
|
+
- [Standalone Tag Usage](#standalone-tag-usage)
|
|
30
44
|
- [Example Tag](#example-tag)
|
|
31
45
|
- [Contributing](#contributing)
|
|
32
46
|
|
|
@@ -34,13 +48,17 @@ Here's the [full documentation](https://rubydoc.info/github/mattruzicka/readme_y
|
|
|
34
48
|
|
|
35
49
|
## Installation
|
|
36
50
|
|
|
37
|
-
Add [gem "readme_yard"](https://rubygems.org/gems/readme_yard) to your
|
|
51
|
+
Add [gem "readme_yard"](https://rubygems.org/gems/readme_yard) to your Gemfile and run `bundle install` or install it yourself with: `gem install readme_yard`
|
|
52
|
+
|
|
53
|
+
**Note:** As of version 0.3.0, Readme Yard requires Ruby 3.0 or higher.
|
|
38
54
|
|
|
39
55
|
## Getting Started
|
|
40
56
|
|
|
41
|
-
Run `readme build` at the command line.
|
|
57
|
+
Run `readme build` at the command line. This creates a README_YARD.md file if there isn't one by copying your existing README.md file.
|
|
58
|
+
|
|
59
|
+
README_YARD.md is the template from which `readme build` generates the README. Readme Yard adds the ability to embed and reference your source code in your README via README_YARD.md.
|
|
42
60
|
|
|
43
|
-
|
|
61
|
+
See [Tag Usage](#tag-usage).
|
|
44
62
|
|
|
45
63
|
---
|
|
46
64
|
|
|
@@ -50,102 +68,124 @@ README_YARD.md is the template from which `readme build` generates the README. I
|
|
|
50
68
|
|
|
51
69
|
`readme build` - Reads from README_YARD.md and writes to README.md.
|
|
52
70
|
|
|
53
|
-
`readme
|
|
71
|
+
`readme yard` - Same as `readme build` + generates yard docs.
|
|
72
|
+
|
|
73
|
+
`readme version` - Prints the current version of ReadmeYard.
|
|
54
74
|
|
|
55
75
|
|
|
56
76
|
---
|
|
57
77
|
|
|
58
78
|
## Tag Usage
|
|
59
79
|
|
|
60
|
-
Readme Yard uses
|
|
80
|
+
Readme Yard uses YARD tags and custom markdown tags. YARD tags live inside Ruby source code. The markdown tags live inside README_YARD.md.
|
|
81
|
+
|
|
82
|
+
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.
|
|
61
83
|
|
|
62
|
-
|
|
84
|
+
### Tag Reference Table
|
|
63
85
|
|
|
64
|
-
|
|
86
|
+
| Tag Type | YARD Syntax (in source code) | Markdown Syntax (in README_YARD.md) | Standalone Tag* | Purpose |
|
|
87
|
+
|----------|------------------------------|-------------------------------------|----------------|---------|
|
|
88
|
+
| Readme | `@readme` | `{@readme ObjectPath}` | N/A | General purpose tag to embed content from source code |
|
|
89
|
+
| Readme (comment) | `@readme comment` | `{@readme ObjectPath}` | `{@comment ObjectPath}` | Embeds only the comment from source code |
|
|
90
|
+
| Readme (code) | `@readme code` | `{@readme ObjectPath}` | `{@code ObjectPath}` | Embeds only code implementation |
|
|
91
|
+
| Readme (source) | `@readme source` | `{@readme ObjectPath}` | `{@source ObjectPath}` | Embeds both comments and code |
|
|
92
|
+
| Readme (value) | `@readme value` | `{@readme ObjectPath}` | `{@value ObjectPath}` | Embeds a Ruby value as a Ruby code block |
|
|
93
|
+
| Readme (string) | `@readme string` | `{@readme ObjectPath}` | `{@string ObjectPath}` | Embeds a Ruby string as normal text |
|
|
94
|
+
| Example | `@example` | `{@example ObjectPath}` | N/A | Embeds example code from YARD @example tags |
|
|
65
95
|
|
|
66
|
-
|
|
96
|
+
> *Standalone tags allow embedding content without requiring corresponding YARD tags in source code. See [Standalone Tag Usage](#standalone-tag-usage) for details.
|
|
67
97
|
|
|
68
98
|
### Examples
|
|
69
99
|
|
|
70
|
-
|
|
100
|
+
The next line is a code snippet if you're looking at the [README](https://github.com/mattruzicka/readme_yard/blob/main/README.md) and `{@readme ReadmeYard::ExampleTag.hello_world}` if you're looking at [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md).
|
|
71
101
|
|
|
72
102
|
```ruby
|
|
73
103
|
#
|
|
74
104
|
# @example
|
|
75
|
-
# ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
105
|
+
# ReadmeYard::ExampleTag.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
76
106
|
#
|
|
107
|
+
def hello_world
|
|
108
|
+
"Hello 🌎 🌍 🌏"
|
|
109
|
+
end
|
|
77
110
|
```
|
|
78
111
|
|
|
79
112
|
|
|
80
|
-
The
|
|
113
|
+
The markdown tag tells Readme Yard to parse the `@readme` tag located above the `hello_world` class method located in [lib/readme_yard/example_tag.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/example_tag.rb).
|
|
81
114
|
|
|
82
115
|
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
116
|
|
|
84
|
-
Last one, `{@readme ReadmeYard#command_line_usage}` is used to generate the "Command Line Usage" section above from the comments
|
|
117
|
+
Last one, `{@readme ReadmeYard#command_line_usage}` is used to generate the "Command Line Usage" section above from the comments of the `command_line_usage` instance method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb). This method is extra meta: it returns the result of formatting its own comments as markdown. In this way, the usage instructions in the comments, the README, and as printed at the command line will always be in sync.
|
|
85
118
|
|
|
86
119
|
---
|
|
87
120
|
|
|
88
121
|
## Readme Tag
|
|
89
122
|
|
|
90
|
-
**
|
|
91
|
-
|
|
92
|
-
**YARD Tag** syntax: `@example <name>`
|
|
123
|
+
**Markdown** syntax: `{@readme ObjectPath}`
|
|
93
124
|
|
|
94
|
-
|
|
95
|
-
will be embedded in the final output.
|
|
125
|
+
**YARD** syntax: `@example <name>`
|
|
96
126
|
|
|
97
|
-
|
|
98
|
-
|
|
127
|
+
By default, only the text nested under a @readme tag
|
|
128
|
+
will be embedded in the final output. The default
|
|
129
|
+
embed behavior can be changed through the use of tag names.
|
|
99
130
|
|
|
100
131
|
|
|
101
|
-
|
|
132
|
+
### Embed comments
|
|
102
133
|
|
|
103
|
-
## Readme YARD Tags
|
|
104
134
|
|
|
135
|
+
**Usage:**
|
|
105
136
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
137
|
+
```ruby
|
|
138
|
+
# @readme comment
|
|
139
|
+
```
|
|
109
140
|
|
|
110
141
|
|
|
111
|
-
|
|
142
|
+
This example [@readme comment](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/comment_tag.rb) tag embeds the below code snippet via the `{@readme ReadmeYard::CommentTag.format_tag}` markdown tag.
|
|
112
143
|
|
|
113
144
|
```ruby
|
|
114
145
|
#
|
|
115
146
|
# This comment is in the README because `@readme comment`
|
|
116
|
-
# is below
|
|
147
|
+
# is below (in the source code).
|
|
117
148
|
#
|
|
118
149
|
```
|
|
119
150
|
|
|
120
151
|
|
|
121
|
-
###
|
|
152
|
+
### Embed Ruby code
|
|
153
|
+
|
|
122
154
|
|
|
123
|
-
|
|
155
|
+
**Usage:**
|
|
156
|
+
|
|
157
|
+
```ruby
|
|
158
|
+
# @readme code
|
|
159
|
+
```
|
|
124
160
|
|
|
125
161
|
|
|
126
|
-
|
|
162
|
+
This example [@readme code](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/code_tag.rb) tag embeds the below code snippet via the `{@readme ReadmeYard::CodeTag.format_tag}` markdown tag.
|
|
127
163
|
|
|
128
164
|
```ruby
|
|
129
|
-
def
|
|
165
|
+
def format_tag(yard_object, _tag)
|
|
130
166
|
ExampleTag.format_ruby(yard_object.source)
|
|
131
167
|
end
|
|
132
168
|
```
|
|
133
169
|
|
|
134
170
|
|
|
171
|
+
### Embed Ruby comments and code
|
|
172
|
+
|
|
135
173
|
|
|
136
|
-
|
|
174
|
+
**Usage:**
|
|
137
175
|
|
|
138
|
-
|
|
176
|
+
```ruby
|
|
177
|
+
# @readme source
|
|
178
|
+
```
|
|
139
179
|
|
|
140
180
|
|
|
141
|
-
|
|
181
|
+
This example [@readme source](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/source_tag.rb) tag embeds the below code snippet via the `{@readme ReadmeYard::SourceTag.format_tag}` markdown tag.
|
|
142
182
|
|
|
143
183
|
```ruby
|
|
144
184
|
#
|
|
145
|
-
#
|
|
146
|
-
# because `@readme
|
|
185
|
+
# The comment and code for ReadmeYard::SourceTag#format_tag
|
|
186
|
+
# is in the README because `@readme source` is below (in the source code).
|
|
147
187
|
#
|
|
148
|
-
def
|
|
188
|
+
def format_tag(yard_object, _tag)
|
|
149
189
|
text = CommentTag.format_docstring_as_comment(yard_object)
|
|
150
190
|
text << "\n#{yard_object.source}"
|
|
151
191
|
ExampleTag.format_ruby(text)
|
|
@@ -153,27 +193,99 @@ end
|
|
|
153
193
|
```
|
|
154
194
|
|
|
155
195
|
|
|
196
|
+
### Embed a Ruby value as a Ruby code block
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
**Usage:**
|
|
200
|
+
|
|
201
|
+
```ruby
|
|
202
|
+
# @readme value
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
This example [@readme value](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/value_tag.rb) tag embeds the below code snippet via the `{@value ReadmeYard::ValueTag::EXAMPLE}` markdown tag.
|
|
207
|
+
|
|
208
|
+
```ruby
|
|
209
|
+
{ key: "value" }.freeze
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Embed a Ruby string as normal text
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
**Usage:**
|
|
216
|
+
|
|
217
|
+
Because a [@readme string](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/string_tag.rb) tag:
|
|
218
|
+
|
|
219
|
+
```ruby
|
|
220
|
+
# @readme string
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
Is located above this constant:
|
|
225
|
+
|
|
226
|
+
```ruby
|
|
227
|
+
XZAMPLE = <<~STRING
|
|
228
|
+
I heard you like self-documenting Ruby, so I wrote
|
|
229
|
+
self-documenting Ruby for your self-documenting Ruby.
|
|
230
|
+
STRING
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
We see can see its string value as simple text below:
|
|
235
|
+
|
|
236
|
+
I heard you like self-documenting Ruby, so I wrote
|
|
237
|
+
self-documenting Ruby for your self-documenting Ruby.
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Standalone Tag Usage
|
|
242
|
+
|
|
243
|
+
While using the `@readme` tag in your source code is recommended because it makes the README's dependency on source code explicit, sometimes it's useful to embed source code snippets directly without it. This is especially valuable when a source object can only contain one `@readme` tag, but you want to highlight multiple aspects of the object.
|
|
244
|
+
|
|
245
|
+
You can use any of these tags directly in README_YARD.md without requiring a corresponding `@readme` tag in the source code:
|
|
246
|
+
|
|
247
|
+
- `{@comment ObjectPath}` - Embeds comments only
|
|
248
|
+
- `{@code ObjectPath}` - Embeds code only
|
|
249
|
+
- `{@source ObjectPath}` - Embeds both comments and code
|
|
250
|
+
- `{@value ObjectPath}` - Embeds a Ruby value as a Ruby code block
|
|
251
|
+
- `{@string ObjectPath}` - Embeds a Ruby string as plain text
|
|
252
|
+
|
|
253
|
+
For example, in the StringTag section above, we used both:
|
|
254
|
+
- `{@code ReadmeYard::StringTag::XZAMPLE}` to show the constant definition
|
|
255
|
+
- `{@string ReadmeYard::StringTag::XZAMPLE}` to display the string value as text
|
|
256
|
+
|
|
257
|
+
The standalone tag usage provides more flexibility when documenting your code and doesn't require modifications to the source files.
|
|
156
258
|
|
|
157
259
|
---
|
|
158
260
|
|
|
159
261
|
## Example Tag
|
|
160
262
|
|
|
161
|
-
**
|
|
263
|
+
**Markdown** syntax: `{@example ObjectPath}`
|
|
264
|
+
|
|
265
|
+
**YARD** syntax: `@example`
|
|
266
|
+
|
|
267
|
+
The Example Tag leverages YARD's standard `@example` tag syntax, allowing you to
|
|
268
|
+
include example code in your README directly from source files. This saves time and
|
|
269
|
+
ensures your README stays in sync with your YARD documentation
|
|
162
270
|
|
|
163
|
-
|
|
271
|
+
|
|
272
|
+
**Usage:**
|
|
164
273
|
|
|
165
274
|
```ruby
|
|
166
275
|
#
|
|
167
276
|
# @example
|
|
168
|
-
# ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
277
|
+
# ReadmeYard::ExampleTag.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
169
278
|
#
|
|
279
|
+
def hello_world
|
|
280
|
+
"Hello 🌎 🌍 🌏"
|
|
281
|
+
end
|
|
170
282
|
```
|
|
171
283
|
|
|
172
284
|
|
|
173
|
-
|
|
285
|
+
The below example code is generated from `{@example ReadmeYard::ExampleTag.hello_world}` because, as you can see above, the "hello_world" class method has an `@example` tag.
|
|
174
286
|
|
|
175
287
|
```ruby
|
|
176
|
-
ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
288
|
+
ReadmeYard::ExampleTag.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
177
289
|
```
|
|
178
290
|
|
|
179
291
|
|
|
@@ -183,6 +295,4 @@ ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
|
|
|
183
295
|
|
|
184
296
|
Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.
|
|
185
297
|
|
|
186
|
-
Thanks for
|
|
187
|
-
|
|
188
|
-
🌿 🥏 🌱 ⚽
|
|
298
|
+
Thanks for reading me, the README that documents how to document the README with code that documents itself 🤯
|