yard-yaml 0.1.1 → 0.1.3
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
- checksums.yaml.gz.sig +0 -0
- data/CHANGELOG.md +42 -1
- data/CONTRIBUTING.md +21 -0
- data/README.md +31 -18
- data/lib/yard/yaml/config.rb +1 -1
- data/lib/yard/yaml/converter.rb +42 -3
- data/lib/yard/yaml/emitter.rb +28 -11
- data/lib/yard/yaml/plugin.rb +68 -2
- data/lib/yard/yaml/version.rb +1 -1
- data/lib/yard-yaml.rb +3 -0
- data/sig/yard/yaml/version.rbs +0 -1
- data.tar.gz.sig +1 -2
- metadata +19 -13
- metadata.gz.sig +0 -0
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9a842a02dca6a487f1a0f4678f20ad5a96ba949f721ea5f12f0a8a6c879cfaaa
|
|
4
|
+
data.tar.gz: b83b602ca51906df5d5365b0cc45a8ba2cd695beb031959224cc192615c26a92
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: e306dcdf85cf5bbe06f70db4fc068f3c562ba762c121db3ca95ff36b16adc1ebd1ec8a2a1dd10309cd9d6dd76f90b874f9f359b01c765ae4c5e2bc14abe6b650
|
|
7
|
+
data.tar.gz: f657aa6e4fd309bafcc8185d3833e57260455b74ae96b393f1aaff7160621303f0f77d20797bbc584c86df9cc27633dafcc7d7a67327485b61316fe47639d42f
|
checksums.yaml.gz.sig
CHANGED
|
Binary file
|
data/CHANGELOG.md
CHANGED
|
@@ -30,6 +30,43 @@ Please file a bug if you notice a violation of semantic versioning.
|
|
|
30
30
|
|
|
31
31
|
### Security
|
|
32
32
|
|
|
33
|
+
## [0.1.3] - 2026-05-27
|
|
34
|
+
|
|
35
|
+
- TAG: [v0.1.3][0.1.3t]
|
|
36
|
+
- COVERAGE: 94.88% -- 519/547 lines in 12 files
|
|
37
|
+
- BRANCH COVERAGE: 83.25% -- 164/197 branches in 12 files
|
|
38
|
+
- 78.38% documented
|
|
39
|
+
|
|
40
|
+
### Fixed
|
|
41
|
+
|
|
42
|
+
- YAML documentation pages no longer truncate long source lines by default,
|
|
43
|
+
preserving full values such as repository URLs in rendered CFF pages.
|
|
44
|
+
|
|
45
|
+
## [0.1.2] - 2026-05-27
|
|
46
|
+
|
|
47
|
+
- TAG: [v0.1.2][0.1.2t]
|
|
48
|
+
- COVERAGE: 94.88% -- 519/547 lines in 12 files
|
|
49
|
+
- BRANCH COVERAGE: 83.25% -- 164/197 branches in 12 files
|
|
50
|
+
- 78.38% documented
|
|
51
|
+
|
|
52
|
+
### Changed
|
|
53
|
+
|
|
54
|
+
- Documented that `yard-yaml` discovers YAML/CFF files through its own globs
|
|
55
|
+
and that listing those files as plain YARD inputs is only needed when users
|
|
56
|
+
intentionally want YARD's raw file-page rendering too.
|
|
57
|
+
|
|
58
|
+
### Fixed
|
|
59
|
+
|
|
60
|
+
- Converted YAML page filenames now default to source paths instead of YAML
|
|
61
|
+
titles, keeping display titles separate from stable output paths and avoiding
|
|
62
|
+
silent overwrites when titles collide.
|
|
63
|
+
- Expanded plugin, logger, registry, and tag-renderer specs so the test suite
|
|
64
|
+
again satisfies the configured line and branch coverage gates.
|
|
65
|
+
- `--plugin yaml` now activates discovery and emits converted YAML pages after
|
|
66
|
+
YARD finishes generating HTML.
|
|
67
|
+
- `Yard::Yaml::Converter` now adapts to `yaml-converter`'s real in-memory
|
|
68
|
+
Markdown API instead of calling an obsolete positional `convert` signature.
|
|
69
|
+
|
|
33
70
|
## [0.1.1] - 2026-05-24
|
|
34
71
|
|
|
35
72
|
- TAG: [v0.1.1][0.1.1t]
|
|
@@ -63,7 +100,11 @@ Please file a bug if you notice a violation of semantic versioning.
|
|
|
63
100
|
|
|
64
101
|
### Security
|
|
65
102
|
|
|
66
|
-
[Unreleased]: https://github.com/galtzo-floss/yard-yaml/compare/v0.1.
|
|
103
|
+
[Unreleased]: https://github.com/galtzo-floss/yard-yaml/compare/v0.1.3...HEAD
|
|
104
|
+
[0.1.3]: https://github.com/galtzo-floss/yard-yaml/compare/v0.1.2...v0.1.3
|
|
105
|
+
[0.1.3t]: https://github.com/galtzo-floss/yard-yaml/releases/tag/v0.1.3
|
|
106
|
+
[0.1.2]: https://github.com/galtzo-floss/yard-yaml/compare/v0.1.1...v0.1.2
|
|
107
|
+
[0.1.2t]: https://github.com/galtzo-floss/yard-yaml/releases/tag/v0.1.2
|
|
67
108
|
[0.1.1]: https://github.com/galtzo-floss/yard-yaml/compare/v0.1.0...v0.1.1
|
|
68
109
|
[0.1.1t]: https://github.com/galtzo-floss/yard-yaml/releases/tag/v0.1.1
|
|
69
110
|
[0.1.0]: https://github.com/galtzo-floss/yard-yaml/compare/ffbe883471d11462dc28675867d852372ea3a481...v0.1.0
|
data/CONTRIBUTING.md
CHANGED
|
@@ -50,6 +50,22 @@ There are many Rake tasks available as well. You can see them by running:
|
|
|
50
50
|
bin/rake -T
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
+
## Code quality checks
|
|
54
|
+
|
|
55
|
+
Run the Reek task when you want a smell check that fails on current findings:
|
|
56
|
+
|
|
57
|
+
```shell
|
|
58
|
+
bin/rake reek
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Refresh the checked-in `REEK` backlog through the rake task, not by redirecting
|
|
62
|
+
the raw `reek` executable output. The rake task uses the project bundle and
|
|
63
|
+
avoids stale generated binstubs shadowing the Reek gem executable:
|
|
64
|
+
|
|
65
|
+
```shell
|
|
66
|
+
bin/rake reek:update
|
|
67
|
+
```
|
|
68
|
+
|
|
53
69
|
## Environment Variables for Local Development
|
|
54
70
|
|
|
55
71
|
Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.
|
|
@@ -91,6 +107,11 @@ For a quick starting point, this repository’s `mise.toml` defines the shared d
|
|
|
91
107
|
## Appraisals
|
|
92
108
|
|
|
93
109
|
From time to time the [appraisal2][🚎appraisal2] gemfiles in `gemfiles/` will need to be updated.
|
|
110
|
+
Generated appraisal and CI workflow floors are controlled by `ruby.test_minimum`
|
|
111
|
+
in `.kettle-jem.yml`; this project was templated with `ruby.test_minimum: 3.2.0`.
|
|
112
|
+
That value describes the lowest Ruby version expected to run the test/development
|
|
113
|
+
toolchain, and it may be higher than the gemspec runtime floor.
|
|
114
|
+
|
|
94
115
|
They are created and updated with the commands:
|
|
95
116
|
|
|
96
117
|
```console
|
data/README.md
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
|
-
[![Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0][🖼️galtzo-floss-i]][🖼️galtzo-floss] [![ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5][🖼️ruby-lang-i]][🖼️ruby-lang]
|
|
1
|
+
[![Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0][🖼️galtzo-floss-i]][🖼️galtzo-floss] [![ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5][🖼️ruby-lang-i]][🖼️ruby-lang] [![yard-yaml Logo by Aboling0, CC BY-SA 4.0][🖼️galtzo-floss-yard-yaml-i]][🖼️galtzo-floss-yard-yaml]
|
|
2
2
|
|
|
3
3
|
[🖼️galtzo-floss-i]: https://logos.galtzo.com/assets/images/galtzo-floss/avatar-192px.svg
|
|
4
4
|
[🖼️galtzo-floss]: https://discord.gg/3qme4XHNKN
|
|
5
5
|
[🖼️ruby-lang-i]: https://logos.galtzo.com/assets/images/ruby-lang/avatar-192px.svg
|
|
6
6
|
[🖼️ruby-lang]: https://www.ruby-lang.org/
|
|
7
|
+
[🖼️galtzo-floss-yard-yaml-i]: https://logos.galtzo.com/assets/images/galtzo-floss/yard-yaml/avatar-192px.svg
|
|
8
|
+
[🖼️galtzo-floss-yard-yaml]: https://github.com/galtzo-floss/yard-yaml
|
|
7
9
|
|
|
8
|
-
#
|
|
10
|
+
# 🦗 Yard::Yaml
|
|
9
11
|
|
|
10
12
|
[![Version][👽versioni]][👽version] [![GitHub tag (latest SemVer)][⛳️tag-img]][⛳️tag] [![License: MIT][📄license-img]][📄license] [![Downloads Rank][👽dl-ranki]][👽dl-rank] [![CodeCov Test Coverage][🏀codecovi]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] [![QLTY Maintainability][🏀qlty-mnti]][🏀qlty-mnt] [![CI Heads][🚎3-hd-wfi]][🚎3-hd-wf] [![CI Runtime Dependencies @ HEAD][🚎12-crh-wfi]][🚎12-crh-wf] [![CI Current][🚎11-c-wfi]][🚎11-c-wf] [![CI Truffle Ruby][🚎9-t-wfi]][🚎9-t-wf] [![CI JRuby][🚎10-j-wfi]][🚎10-j-wf] [![Deps Locked][🚎13-🔒️-wfi]][🚎13-🔒️-wf] [![Deps Unlocked][🚎14-🔓️-wfi]][🚎14-🔓️-wf] [![CI Test Coverage][🚎2-cov-wfi]][🚎2-cov-wf] [![CI Style][🚎5-st-wfi]][🚎5-st-wf] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Apache SkyWalking Eyes License Compatibility Check][🚎15-🪪-wfi]][🚎15-🪪-wf]
|
|
11
13
|
|
|
@@ -27,13 +29,15 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
|
|
|
27
29
|
## 🌻 Synopsis
|
|
28
30
|
|
|
29
31
|
To enable the `yard-yaml` plugin add it to your Gemfile,
|
|
30
|
-
and then add the
|
|
32
|
+
and then add the plugin to your `.yardopts` file:
|
|
31
33
|
|
|
32
34
|
```text
|
|
33
35
|
--plugin yaml
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
When you run `yard doc`, `yard-yaml` converts those YAML documents into HTML
|
|
39
|
+
documentation pages under `docs/yaml/`. For example, a root `CITATION.cff`
|
|
40
|
+
with `title: my-gem` becomes a converted page like `docs/yaml/my-gem.html`.
|
|
37
41
|
|
|
38
42
|
## 💡 Info you can shake a stick at
|
|
39
43
|
|
|
@@ -54,6 +58,10 @@ This will activate the plugin during the `yard doc` generation process, converti
|
|
|
54
58
|
### Compatibility
|
|
55
59
|
|
|
56
60
|
Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRuby.
|
|
61
|
+
CI workflows and Appraisals are generated for MRI Ruby 3.2.0+.
|
|
62
|
+
This test floor is configured by `ruby.test_minimum` in `.kettle-jem.yml` and
|
|
63
|
+
may be higher than the gem's runtime compatibility floor when legacy Rubies are
|
|
64
|
+
not practical for the current toolchain.
|
|
57
65
|
|
|
58
66
|
| 🚚 _Amazing_ test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚 |
|
|
59
67
|
|------------------------------------------------|--------------------------------------------------------|
|
|
@@ -128,14 +136,17 @@ The `yard-yaml` plugin supports the following configuration options:
|
|
|
128
136
|
- **strict**: Raise errors on conversion failures (default: `false`).
|
|
129
137
|
- **allow_erb**: Allow ERB processing in YAML files (default: `false`).
|
|
130
138
|
|
|
131
|
-
Note: Citation File Format (`.cff`) files are valid YAML
|
|
139
|
+
Note: Citation File Format (`.cff`) files are valid YAML. The default
|
|
140
|
+
`yard-yaml` discovery globs include root `.cff` files. Do not list YAML/CFF
|
|
141
|
+
files as plain YARD inputs unless you intentionally want YARD's raw file-page
|
|
142
|
+
rendering in addition to the converted `yard-yaml` page.
|
|
132
143
|
|
|
133
144
|
### Example `.yardopts` Configuration
|
|
134
145
|
|
|
135
146
|
```text
|
|
136
147
|
--plugin yaml
|
|
137
|
-
--yard_yaml-include "examples
|
|
138
|
-
--yard_yaml-exclude "/drafts/*.yml"
|
|
148
|
+
--yard_yaml-include "examples/*.yml"
|
|
149
|
+
--yard_yaml-exclude "examples/drafts/*.yml"
|
|
139
150
|
--yard_yaml-out_dir "custom_output"
|
|
140
151
|
--yard_yaml-strict
|
|
141
152
|
```
|
|
@@ -167,17 +178,18 @@ The `yard-yaml` plugin introduces two new tags for use in docstrings:
|
|
|
167
178
|
# @yaml_file path/to/example.yml
|
|
168
179
|
```
|
|
169
180
|
|
|
170
|
-
#### Include .yml/.yaml files as pages
|
|
181
|
+
#### Include .yml/.yaml/.cff files as pages
|
|
171
182
|
|
|
172
|
-
-
|
|
183
|
+
- `yard-yaml` discovery defaults already include root `.yml`/`.yaml`/`.cff`
|
|
184
|
+
files and `docs/**/*.yml`, `docs/**/*.yaml`, and `docs/**/*.cff`; use
|
|
185
|
+
`--yard_yaml-include` for additional converted-page globs.
|
|
186
|
+
- Generate docs:
|
|
173
187
|
```bash
|
|
174
188
|
bundle exec yard
|
|
175
189
|
```
|
|
176
|
-
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
```
|
|
180
|
-
Result: `docs/yaml/<slug>.html` and `docs/yaml/index.html` (when index enabled). Front matter supports `title`, `description`, `nav_order`, optional `slug`.
|
|
190
|
+
Result: `yard-yaml` writes converted pages such as `docs/yaml/<slug>.html`
|
|
191
|
+
plus `docs/yaml/index.html` when index generation is enabled. Front matter
|
|
192
|
+
supports `title`, `description`, `nav_order`, and optional `slug`.
|
|
181
193
|
|
|
182
194
|
#### Inline YAML in Markdown (GFM) fences
|
|
183
195
|
|
|
@@ -514,7 +526,7 @@ Thanks for RTFM. ☺️
|
|
|
514
526
|
[🤝cb-pulls]: https://codeberg.org/galtzo-floss/yard-yaml/pulls
|
|
515
527
|
[🤝cb-donate]: https://donate.codeberg.org/
|
|
516
528
|
[🤝contributing]: https://github.com/galtzo-floss/yard-yaml/blob/main/CONTRIBUTING.md
|
|
517
|
-
[🏀codecov-g]: https://codecov.io/gh/galtzo-floss/yard-yaml/
|
|
529
|
+
[🏀codecov-g]: https://codecov.io/gh/galtzo-floss/yard-yaml/graph/badge.svg
|
|
518
530
|
[🖐contrib-rocks]: https://contrib.rocks
|
|
519
531
|
[🖐contributors]: https://github.com/galtzo-floss/yard-yaml/graphs/contributors
|
|
520
532
|
[🖐contributors-img]: https://contrib.rocks/image?repo=galtzo-floss/yard-yaml
|
|
@@ -532,7 +544,7 @@ Thanks for RTFM. ☺️
|
|
|
532
544
|
[📌gitmoji]: https://gitmoji.dev
|
|
533
545
|
[📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
|
|
534
546
|
[🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
535
|
-
[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.
|
|
547
|
+
[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.547-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
|
|
536
548
|
[🔐security]: https://github.com/galtzo-floss/yard-yaml/blob/main/SECURITY.md
|
|
537
549
|
[🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
|
|
538
550
|
[📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
|
|
@@ -541,6 +553,7 @@ Thanks for RTFM. ☺️
|
|
|
541
553
|
[📄license-img]: https://img.shields.io/badge/License-MIT-259D6C.svg
|
|
542
554
|
[📄license-compat]: https://www.apache.org/legal/resolved.html#category-a
|
|
543
555
|
[📄license-compat-img]: https://img.shields.io/badge/Apache_Compatible:_Category_A-✓-259D6C.svg?style=flat&logo=Apache
|
|
556
|
+
|
|
544
557
|
[📄ilo-declaration]: https://www.ilo.org/declaration/lang--en/index.htm
|
|
545
558
|
[📄ilo-declaration-img]: https://img.shields.io/badge/ILO_Fundamental_Principles-✓-259D6C.svg?style=flat
|
|
546
559
|
[🚎yard-current]: http://rubydoc.info/gems/yard-yaml
|
|
@@ -557,9 +570,9 @@ Thanks for RTFM. ☺️
|
|
|
557
570
|
| Field | Value |
|
|
558
571
|
|---|---|
|
|
559
572
|
| Package | yard-yaml |
|
|
560
|
-
| Description |
|
|
573
|
+
| Description | 🦗 A YARD plugin for YAML documents |
|
|
561
574
|
| Homepage | https://github.com/galtzo-floss/yard-yaml |
|
|
562
|
-
| Source | https://github.com/galtzo-floss/yard-yaml/tree/v0.1.
|
|
575
|
+
| Source | https://github.com/galtzo-floss/yard-yaml/tree/v0.1.2 |
|
|
563
576
|
| License | `MIT` |
|
|
564
577
|
| Funding | https://github.com/sponsors/pboling, https://issuehunt.io/u/pboling, https://ko-fi.com/pboling, https://liberapay.com/pboling/donate, https://opencollective.com/galtzo-floss, https://patreon.com/galtzo, https://polar.sh/pboling, https://thanks.dev/u/gh/pboling, https://tidelift.com/funding/github/rubygems/yard-yaml, https://www.buymeacoffee.com/pboling |
|
|
565
578
|
<!-- kettle-jem:metadata:end -->
|
data/lib/yard/yaml/config.rb
CHANGED
|
@@ -35,7 +35,7 @@ module Yard
|
|
|
35
35
|
DEFAULT_TOC = "auto"
|
|
36
36
|
|
|
37
37
|
# Options forwarded to yaml-converter.
|
|
38
|
-
DEFAULT_CONVERTER_OPTIONS = {}.freeze
|
|
38
|
+
DEFAULT_CONVERTER_OPTIONS = {truncate: false}.freeze
|
|
39
39
|
|
|
40
40
|
# Whether to respect YAML front matter for title/nav order.
|
|
41
41
|
DEFAULT_FRONT_MATTER = true
|
data/lib/yard/yaml/converter.rb
CHANGED
|
@@ -17,7 +17,9 @@ module Yard
|
|
|
17
17
|
|
|
18
18
|
class << self
|
|
19
19
|
# Assignable backend for dependency injection in tests.
|
|
20
|
-
#
|
|
20
|
+
# Preferred backends respond to `to_markdown(yaml, options:)`. Legacy
|
|
21
|
+
# test backends may respond to `convert(yaml, options)` and return a
|
|
22
|
+
# Hash with :html, :title, :description, and :meta keys.
|
|
21
23
|
def backend=(backend)
|
|
22
24
|
BACKEND_MUTEX.synchronize { BACKEND_STATE[:backend] = backend }
|
|
23
25
|
end
|
|
@@ -102,19 +104,56 @@ module Yard
|
|
|
102
104
|
def run_convert(yaml, options, config)
|
|
103
105
|
opts = build_options(options, config)
|
|
104
106
|
b = backend
|
|
105
|
-
unless
|
|
107
|
+
unless converter_backend?(b)
|
|
106
108
|
handle_error(Yard::Yaml::Error.new("yaml-converter backend not available"), strict: config.strict, context: "backend")
|
|
107
109
|
return empty_result
|
|
108
110
|
end
|
|
109
111
|
|
|
110
112
|
begin
|
|
111
|
-
normalize_result(b
|
|
113
|
+
normalize_result(convert_with_backend(b, yaml, opts))
|
|
112
114
|
rescue StandardError => e
|
|
113
115
|
handle_error(e, strict: config.strict, context: opts[:source_path] || "string")
|
|
114
116
|
empty_result
|
|
115
117
|
end
|
|
116
118
|
end
|
|
117
119
|
|
|
120
|
+
def converter_backend?(backend)
|
|
121
|
+
backend&.respond_to?(:to_markdown) || backend&.respond_to?(:convert)
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
def convert_with_backend(backend, yaml, options)
|
|
125
|
+
return convert_markdown_backend(backend, yaml, options) if backend.respond_to?(:to_markdown)
|
|
126
|
+
|
|
127
|
+
backend.convert(yaml, options)
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
def convert_markdown_backend(backend, yaml, options)
|
|
131
|
+
markdown = backend.to_markdown(yaml, options: options)
|
|
132
|
+
metadata = metadata_from_yaml(yaml)
|
|
133
|
+
{
|
|
134
|
+
html: markdown_to_html(markdown),
|
|
135
|
+
title: metadata["title"],
|
|
136
|
+
description: metadata["abstract"],
|
|
137
|
+
meta: metadata,
|
|
138
|
+
}
|
|
139
|
+
end
|
|
140
|
+
|
|
141
|
+
def markdown_to_html(markdown)
|
|
142
|
+
require "kramdown"
|
|
143
|
+
require "kramdown-parser-gfm"
|
|
144
|
+
|
|
145
|
+
Kramdown::Document.new(markdown.to_s, input: "GFM").to_html
|
|
146
|
+
end
|
|
147
|
+
|
|
148
|
+
def metadata_from_yaml(yaml)
|
|
149
|
+
require "yaml"
|
|
150
|
+
|
|
151
|
+
parsed = YAML.safe_load(yaml.to_s, permitted_classes: [], permitted_symbols: [], aliases: false)
|
|
152
|
+
parsed.is_a?(Hash) ? parsed : {}
|
|
153
|
+
rescue Psych::Exception
|
|
154
|
+
{}
|
|
155
|
+
end
|
|
156
|
+
|
|
118
157
|
def build_options(options, config)
|
|
119
158
|
safe = {
|
|
120
159
|
allow_erb: !!config.allow_erb,
|
data/lib/yard/yaml/emitter.rb
CHANGED
|
@@ -25,13 +25,14 @@ module Yard
|
|
|
25
25
|
# @return [Array<String>] list of written file paths
|
|
26
26
|
def emit!(pages:, output_dir:, config: Yard::Yaml.config)
|
|
27
27
|
pages = Array(pages)
|
|
28
|
+
pages_with_slugs = assign_slugs(pages)
|
|
28
29
|
written = []
|
|
29
30
|
base = File.join(output_dir.to_s, config.out_dir.to_s)
|
|
30
31
|
FileUtils.mkdir_p(base)
|
|
31
32
|
|
|
32
33
|
# Write per-page files
|
|
33
|
-
|
|
34
|
-
slug =
|
|
34
|
+
pages_with_slugs.each do |page|
|
|
35
|
+
slug = page.fetch(:__yard_yaml_slug)
|
|
35
36
|
path = File.join(base, "#{slug}.html")
|
|
36
37
|
html = render_page_html(page)
|
|
37
38
|
atomic_write(path, html, strict: config.strict)
|
|
@@ -41,7 +42,7 @@ module Yard
|
|
|
41
42
|
# Index (optional)
|
|
42
43
|
if config.index
|
|
43
44
|
index_path = File.join(base, "index.html")
|
|
44
|
-
html = render_index_html(
|
|
45
|
+
html = render_index_html(pages_with_slugs)
|
|
45
46
|
atomic_write(index_path, html, strict: config.strict)
|
|
46
47
|
written << index_path
|
|
47
48
|
end
|
|
@@ -58,20 +59,36 @@ module Yard
|
|
|
58
59
|
|
|
59
60
|
private
|
|
60
61
|
|
|
62
|
+
def assign_slugs(pages)
|
|
63
|
+
seen = Hash.new(0)
|
|
64
|
+
pages.map do |page|
|
|
65
|
+
slug = page_slug(page)
|
|
66
|
+
count = seen[slug]
|
|
67
|
+
seen[slug] += 1
|
|
68
|
+
page.merge(__yard_yaml_slug: count.zero? ? slug : "#{slug}-#{count + 1}")
|
|
69
|
+
end
|
|
70
|
+
end
|
|
71
|
+
|
|
61
72
|
def page_slug(page)
|
|
62
73
|
meta = page[:meta] || {}
|
|
63
74
|
slug = meta["slug"] || meta[:slug]
|
|
64
75
|
return sanitize_slug(slug) if slug && !slug.to_s.empty?
|
|
65
76
|
|
|
66
|
-
title = page[:title].to_s
|
|
67
|
-
return sanitize_slug(title) unless title.empty?
|
|
68
|
-
|
|
69
77
|
if page[:path]
|
|
70
|
-
|
|
71
|
-
return
|
|
78
|
+
path_slug = path_slug(page[:path])
|
|
79
|
+
return path_slug unless path_slug.empty?
|
|
72
80
|
end
|
|
73
81
|
|
|
74
|
-
|
|
82
|
+
title = sanitize_slug(page[:title])
|
|
83
|
+
title.empty? ? "page" : title
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def path_slug(path)
|
|
87
|
+
relative = path.to_s.delete_prefix("#{Dir.pwd}/")
|
|
88
|
+
dirname = File.dirname(relative)
|
|
89
|
+
basename = File.basename(relative, File.extname(relative))
|
|
90
|
+
parts = (dirname == ".") ? [basename] : dirname.split(File::SEPARATOR) + [basename]
|
|
91
|
+
sanitize_slug(parts.join("-"))
|
|
75
92
|
end
|
|
76
93
|
|
|
77
94
|
def sanitize_slug(s)
|
|
@@ -108,8 +125,8 @@ module Yard
|
|
|
108
125
|
|
|
109
126
|
def render_index_html(pages)
|
|
110
127
|
rows = pages.map do |p|
|
|
111
|
-
|
|
112
|
-
|
|
128
|
+
slug = p[:__yard_yaml_slug] || page_slug(p)
|
|
129
|
+
title = p[:title] || slug
|
|
113
130
|
desc = p[:description]
|
|
114
131
|
%(<li><a href="#{escape_html(slug)}.html">#{escape_html(title)}</a>#{" — #{escape_html(desc)}" if desc}</li>)
|
|
115
132
|
end.join("\n")
|
data/lib/yard/yaml/plugin.rb
CHANGED
|
@@ -4,7 +4,7 @@ module Yard
|
|
|
4
4
|
module Yaml
|
|
5
5
|
# Plugin activation for yard-yaml (Phase 3: config + discovery; still no YARD registrations).
|
|
6
6
|
module Plugin
|
|
7
|
-
STATE = {activated: false}
|
|
7
|
+
STATE = {activated: false, at_exit_installed: false}
|
|
8
8
|
STATE_MUTEX = Mutex.new
|
|
9
9
|
|
|
10
10
|
class << self
|
|
@@ -49,12 +49,78 @@ module Yard
|
|
|
49
49
|
nil
|
|
50
50
|
end
|
|
51
51
|
|
|
52
|
+
# Install an at-exit emitter for YARD's plugin loader. YARD loads
|
|
53
|
+
# plugins before it has generated the HTML tree, so converted YAML
|
|
54
|
+
# pages must be written after YARD finishes.
|
|
55
|
+
#
|
|
56
|
+
# @param argv [Array<String>, nil] the YARD argv used to discover output
|
|
57
|
+
# @return [void]
|
|
58
|
+
def install_at_exit(argv = nil)
|
|
59
|
+
should_install = STATE_MUTEX.synchronize do
|
|
60
|
+
if STATE[:at_exit_installed]
|
|
61
|
+
false
|
|
62
|
+
else
|
|
63
|
+
STATE[:at_exit_installed] = true
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
return unless should_install
|
|
67
|
+
|
|
68
|
+
at_exit do
|
|
69
|
+
emit!(output_dir: yard_output_dir(argv || ARGV))
|
|
70
|
+
end
|
|
71
|
+
nil
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
# Emit converted pages collected during activation.
|
|
75
|
+
#
|
|
76
|
+
# @param output_dir [String] YARD HTML output directory
|
|
77
|
+
# @return [Array<String>]
|
|
78
|
+
def emit!(output_dir:)
|
|
79
|
+
pages = Yard::Yaml.pages
|
|
80
|
+
return [] if pages.nil? || pages.empty?
|
|
81
|
+
|
|
82
|
+
Yard::Yaml::Emitter.emit!(pages: pages, output_dir: output_dir, config: Yard::Yaml.config)
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
# Resolve YARD's HTML output directory from argv or .yardopts.
|
|
86
|
+
#
|
|
87
|
+
# @param argv [Array<String>]
|
|
88
|
+
# @return [String]
|
|
89
|
+
def yard_output_dir(argv)
|
|
90
|
+
output_dir_from_tokens(Array(argv).map(&:to_s)) ||
|
|
91
|
+
output_dir_from_tokens(yardopts_tokens) ||
|
|
92
|
+
"doc"
|
|
93
|
+
end
|
|
94
|
+
|
|
52
95
|
# Test-helper: reset internal activation flag.
|
|
53
96
|
# Not part of public API; used from test teardown to avoid state leakage.
|
|
54
97
|
def __reset_state__
|
|
55
|
-
STATE_MUTEX.synchronize
|
|
98
|
+
STATE_MUTEX.synchronize do
|
|
99
|
+
STATE[:activated] = false
|
|
100
|
+
STATE[:at_exit_installed] = false
|
|
101
|
+
end
|
|
102
|
+
nil
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
private
|
|
106
|
+
|
|
107
|
+
def output_dir_from_tokens(tokens)
|
|
108
|
+
tokens.each_with_index do |token, index|
|
|
109
|
+
return tokens[index + 1] if token == "--output" || token == "-o"
|
|
110
|
+
match = token.match(/\A--output=(.+)\z/)
|
|
111
|
+
return match[1] if match
|
|
112
|
+
end
|
|
56
113
|
nil
|
|
57
114
|
end
|
|
115
|
+
|
|
116
|
+
def yardopts_tokens
|
|
117
|
+
return [] unless File.file?(".yardopts")
|
|
118
|
+
|
|
119
|
+
require "shellwords"
|
|
120
|
+
Shellwords.split(File.read(".yardopts"))
|
|
121
|
+
rescue StandardError
|
|
122
|
+
[]
|
|
123
|
+
end
|
|
58
124
|
end
|
|
59
125
|
end
|
|
60
126
|
end
|
data/lib/yard/yaml/version.rb
CHANGED
data/lib/yard-yaml.rb
CHANGED
data/sig/yard/yaml/version.rbs
CHANGED
data.tar.gz.sig
CHANGED
|
@@ -1,2 +1 @@
|
|
|
1
|
-
|
|
2
|
-
�ޏ:��C�'�;R6i�� ~��l�����Թ�m@$m�B�h5�f�G�H%�mcY�
|
|
1
|
+
�8Tq�J$�Ho� �� -5�.xn&jk��+١�� ԟe䤢݅j��4�"��E��z� $݁�Z�7��������xƋQ�Id��p�i���G��0��[�\�n-Q��D��C{���`�.��ɔpz�����X#�/%}B����#"�좻��rQ,vl�� �u,� �O]�/ +bȐ~������� ��(j#b !Փ��$q �bחc�VZ�ŀO�ϳ��yUކ�^� `��ʪx���6�B
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: yard-yaml
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1.
|
|
4
|
+
version: 0.1.3
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Annibelle Boling
|
|
@@ -79,6 +79,9 @@ dependencies:
|
|
|
79
79
|
- - "~>"
|
|
80
80
|
- !ruby/object:Gem::Version
|
|
81
81
|
version: '2.0'
|
|
82
|
+
- - ">="
|
|
83
|
+
- !ruby/object:Gem::Version
|
|
84
|
+
version: 2.0.1
|
|
82
85
|
type: :development
|
|
83
86
|
prerelease: false
|
|
84
87
|
version_requirements: !ruby/object:Gem::Requirement
|
|
@@ -86,6 +89,9 @@ dependencies:
|
|
|
86
89
|
- - "~>"
|
|
87
90
|
- !ruby/object:Gem::Version
|
|
88
91
|
version: '2.0'
|
|
92
|
+
- - ">="
|
|
93
|
+
- !ruby/object:Gem::Version
|
|
94
|
+
version: 2.0.1
|
|
89
95
|
- !ruby/object:Gem::Dependency
|
|
90
96
|
name: bundler-audit
|
|
91
97
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -163,7 +169,7 @@ dependencies:
|
|
|
163
169
|
version: '2.0'
|
|
164
170
|
- - ">="
|
|
165
171
|
- !ruby/object:Gem::Version
|
|
166
|
-
version: 2.0.
|
|
172
|
+
version: 2.0.1
|
|
167
173
|
type: :development
|
|
168
174
|
prerelease: false
|
|
169
175
|
version_requirements: !ruby/object:Gem::Requirement
|
|
@@ -173,7 +179,7 @@ dependencies:
|
|
|
173
179
|
version: '2.0'
|
|
174
180
|
- - ">="
|
|
175
181
|
- !ruby/object:Gem::Version
|
|
176
|
-
version: 2.0.
|
|
182
|
+
version: 2.0.1
|
|
177
183
|
- !ruby/object:Gem::Dependency
|
|
178
184
|
name: ruby-progressbar
|
|
179
185
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -214,21 +220,21 @@ dependencies:
|
|
|
214
220
|
requirements:
|
|
215
221
|
- - "~>"
|
|
216
222
|
- !ruby/object:Gem::Version
|
|
217
|
-
version: '
|
|
223
|
+
version: '2.0'
|
|
218
224
|
- - ">="
|
|
219
225
|
- !ruby/object:Gem::Version
|
|
220
|
-
version:
|
|
226
|
+
version: 2.0.0
|
|
221
227
|
type: :development
|
|
222
228
|
prerelease: false
|
|
223
229
|
version_requirements: !ruby/object:Gem::Requirement
|
|
224
230
|
requirements:
|
|
225
231
|
- - "~>"
|
|
226
232
|
- !ruby/object:Gem::Version
|
|
227
|
-
version: '
|
|
233
|
+
version: '2.0'
|
|
228
234
|
- - ">="
|
|
229
235
|
- !ruby/object:Gem::Version
|
|
230
|
-
version:
|
|
231
|
-
description: "\
|
|
236
|
+
version: 2.0.0
|
|
237
|
+
description: "\U0001F997 A YARD plugin for YAML documents"
|
|
232
238
|
email:
|
|
233
239
|
- floss@galtzo.com
|
|
234
240
|
executables: []
|
|
@@ -274,10 +280,10 @@ licenses:
|
|
|
274
280
|
- MIT
|
|
275
281
|
metadata:
|
|
276
282
|
homepage_uri: https://structuredmerge.org
|
|
277
|
-
source_code_uri: https://github.com/galtzo-floss/yard-yaml/tree/v0.1.
|
|
278
|
-
changelog_uri: https://github.com/galtzo-floss/yard-yaml/blob/v0.1.
|
|
283
|
+
source_code_uri: https://github.com/galtzo-floss/yard-yaml/tree/v0.1.3
|
|
284
|
+
changelog_uri: https://github.com/galtzo-floss/yard-yaml/blob/v0.1.3/CHANGELOG.md
|
|
279
285
|
bug_tracker_uri: https://github.com/galtzo-floss/yard-yaml/issues
|
|
280
|
-
documentation_uri: https://www.rubydoc.info/gems/yard-yaml/0.1.
|
|
286
|
+
documentation_uri: https://www.rubydoc.info/gems/yard-yaml/0.1.3
|
|
281
287
|
funding_uri: https://github.com/sponsors/pboling
|
|
282
288
|
wiki_uri: https://github.com/galtzo-floss/yard-yaml/wiki
|
|
283
289
|
news_uri: https://www.railsbling.com/tags/yard-yaml
|
|
@@ -285,7 +291,7 @@ metadata:
|
|
|
285
291
|
rubygems_mfa_required: 'true'
|
|
286
292
|
rdoc_options:
|
|
287
293
|
- "--title"
|
|
288
|
-
- "yard-yaml - \
|
|
294
|
+
- "yard-yaml - \U0001F997 A YARD plugin for YAML documents"
|
|
289
295
|
- "--main"
|
|
290
296
|
- README.md
|
|
291
297
|
- "--exclude"
|
|
@@ -308,5 +314,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
308
314
|
requirements: []
|
|
309
315
|
rubygems_version: 4.0.10
|
|
310
316
|
specification_version: 4
|
|
311
|
-
summary: "\
|
|
317
|
+
summary: "\U0001F997 A YARD plugin for YAML documents"
|
|
312
318
|
test_files: []
|
metadata.gz.sig
CHANGED
|
Binary file
|