yard-fence 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cab9d088b1349a451adc56f4b43e267d8c94844044812b66c5a57eed3289148b
-  data.tar.gz: d53f16b1762b761fa412527e325fccf3f0d2338d8d90e08f1b08a578d7f42ce2
+  metadata.gz: aaa318b924e8efbaddbb3666df3f71157678a5fbab11972f51550ecd48f4ddb2
+  data.tar.gz: af4bb34d3b799695511f5b880aa1fffa7d9765dcb71a8c5c780bfbd53f5d9f35
 SHA512:
-  metadata.gz: 164bcdf2a12d36a560ee1da0588de321822d16861e1b7c3ceed37bc1ec4a0bae89818b43fdb065ba8285a8512e9429ad5d21c2ab9a1fadfa2badfb627fe727a8
-  data.tar.gz: f92d68174febc61638fb8c7537882062aafa9547f6afdfa2299e9937d861ba0e4ca67a1c1efccba3d5d6d969b6e5ce5742fac335e510036eaa26a2c1b6e49225
+  metadata.gz: c59ecea9ee908fe804879b2197ab6047769d70a2256e69522afff4069ad73e95b48f370f0ab9a1827dc4f955e2e1f3ded8c7017da27869c0cb2b262e986f910c
+  data.tar.gz: 4ed6d00979a897c5ced52a0c72ae108c2eb05a29be9e73b9e0dd5bbc1546e80c6f54a1d780460b4a41268e0dcac27cff10142e70fb7826755f8ba511a6715508

data/CHANGELOG.md

@@ -30,6 +30,37 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.4.0] - 2025-11-07
+
+- TAG: [v0.4.0][0.4.0t]
+- COVERAGE: 96.43% -- 81/84 lines in 4 files
+- BRANCH COVERAGE: 93.75% -- 15/16 branches in 4 files
+- 29.17% documented
+
+### Added
+
+- Docs: Document importance of `require: false` in `Gemfile` for this gem
+
+### Changed
+
+- Docs: Improved markdown syntax in README.md for Kramdown => HTML
+
+### Fixed
+
+- Use namespaced directory in `tmp/` (`tmp/yard-fence`)
+  - avoids polluting, and pollution from, other garbage in `tmp/`
+
+## [0.3.0] - 2025-11-07
+
+- TAG: [v0.3.0][0.3.0t]
+- COVERAGE: 96.43% -- 81/84 lines in 4 files
+- BRANCH COVERAGE: 93.75% -- 15/16 branches in 4 files
+- 29.17% documented
+
+### Added
+
+- yard/fence/hoist.rb: Hoisting the customized GFM kramdown parser
+
 ## [0.2.0] - 2025-11-07
 
 - TAG: [v0.2.0][0.2.0t]
@@ -51,6 +82,10 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/galtzo-floss/yard-fence/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/galtzo-floss/yard-fence/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.3.0...v0.4.0
+[0.4.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.4.0
+[0.3.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.2.0...v0.3.0
+[0.3.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.3.0
 [0.2.0]: https://github.com/galtzo-floss/yard-fence/compare/v0.1.0...v0.2.0
 [0.2.0t]: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.2.0

data/README.md

@@ -51,11 +51,28 @@
 A brace converter for the markdown fences in your YARD docs to prevent the `InvalidLink` warning.
 
 Just the important bits:
-- Preprocesses top-level README and other `.md`/`.txt` files into `tmp/` replacing ASCII braces inside fenced code blocks, inline code spans, and simple placeholders like `{issuer}` or `{{TOKEN}}` with visually identical fullwidth braces.
+
+- Preprocesses top-level README and other `.md`/`.txt` files into `tmp/yard-fence/` replacing ASCII braces inside fenced code blocks, inline code spans, and simple placeholders like `{issuer}` or `{{TOKEN}}` with visually identical fullwidth braces.
 - This prevents YARD from emitting `InvalidLink` warnings.
 - Prioritizes Kramdown's GFM parser so tables and fenced code blocks render correctly.
 - After YARD finishes generating HTML, restores fullwidth braces back to normal ASCII braces so code examples are copy‑pastable.
 
+Create a `.yardopts` file like this:
+
+```text
+--plugin fence
+-e yard/fence/hoist.rb
+--readme tmp/yard-fence/README.md
+--markup markdown
+--output docs
+'lib/**/*.rb'
+-
+'tmp/yard-fence/*.md'
+'tmp/yard-fence/*.txt'
+```
+
+See the configuration and usage sections for more details.
+
 ## 💡 Info you can shake a stick at
 
 | Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                                                          |
@@ -81,7 +98,7 @@ Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRu
 
 ### Federated DVCS
 
-<details>
+<details markdown="1">
   <summary>Find this repo on federated forges (Coming soon!)</summary>
 
 | Federated [DVCS][💎d-in-dvcs] Repository           | Status                                                                | Issues                    | PRs                      | Wiki                      | CI                       | Discussions                  |
@@ -99,7 +116,7 @@ Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRu
 
 Available as part of the Tidelift Subscription.
 
-<details>
+<details markdown="1">
   <summary>Need enterprise-level guarantees?</summary>
 
 The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
@@ -123,7 +140,18 @@ Alternatively:
 Install the gem and add to the application's Gemfile by executing:
 
 ```console
-bundle add yard-fence
+bundle add yard-fence --require false
+```
+
+NOTE: if you add it directly to your Gemfile,
+be sure to include `require: false` so bundler doesn't load it when bootstrapping.
+This is important because this gem has a global `at_exit` callback that only makes sense to run after yard runs.
+As such this gem should only be loaded by YARD itself via the `--plugin fence` option.
+
+Example:
+
+```ruby
+gem "yard-fence", "~> 0.3", require: false
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
@@ -134,7 +162,7 @@ gem install yard-fence
 
 ### 🔒 Secure Installation
 
-<details>
+<details markdown="1">
   <summary>For Medium or High Security Installations</summary>
 
 This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by
@@ -169,24 +197,25 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ## ⚙️ Configuration
 
-Yard::Fence writes sanitized copies of top‑level Markdown/TXT into tmp/ at load time. To avoid YARD parsing the unsanitized originals, point YARD at the tmp/ copies.
+NOTE: `Yard::Fence` writes sanitized copies of top‑level Markdown/TXT into `tmp/yard-fence/` at load time. To avoid YARD parsing the unsanitized originals, point YARD at the `tmp/yard-fence/` copies.
 
 Recommended .yardopts (noise‑free):
 
 ```text
 --plugin fence
--e 'Yard::Fence.use_kramdown_gfm!'
---readme tmp/README.md
+-e yard/fence/hoist.rb
+--readme tmp/yard-fence/README.md
 --markup markdown
 --output docs
 'lib/**/*.rb'
 -
-'tmp/*.md'
-'tmp/*.txt'
+'tmp/yard-fence/*.md'
+'tmp/yard-fence/*.txt'
 ```
 
-Why tmp/?
-- The plugin converts ASCII `{ }` to fullwidth `｛ ｝` only in `tmp/` so YARD won’t treat brace content as reference tags and emit InvalidLink warnings. After docs are generated, the HTML is restored back to normal ASCII braces for easy copy/paste.
+Why tmp/yard-fence/?
+
+- The plugin converts ASCII `{ }` to fullwidth `｛ ｝` only in `tmp/yard-fence/` so YARD won’t treat brace content as reference tags and emit `InvalidLink` warnings. After docs are generated, the HTML is restored back to normal ASCII braces for easy copy/paste.
 
 ## 🔧 Basic Usage
 
@@ -195,9 +224,9 @@ CLI example that would be similar to what is accomplished by the `.yardopts` fro
 ```bash
 yard doc \
   --plugin fence \
-  -e 'Yard::Fence.use_kramdown_gfm!' \
-  --readme tmp/README.md \
-  lib/**/*.rb - tmp/*.md tmp/*.txt
+  -e yard/fence/hoist.rb \
+  --readme tmp/yard-fence/README.md \
+  lib/**/*.rb - tmp/yard-fence/*.md tmp/yard-fence/*.txt
 ```
 
 ## 🦷 FLOSS Funding
@@ -328,10 +357,10 @@ the [Pessimistic Version Constraint][📌pvc] with two digits of precision.
 For example:
 
 ```ruby
-spec.add_dependency("yard-fence", "~> 1.0")
+spec.add_dependency("yard-fence", "~> 0.4")
 ```
 
-<details>
+<details markdown="1">
 <summary>📌 Is "Platform Support" part of the public API? More details inside.</summary>
 
 SemVer should, IMO, but doesn't explicitly, say that dropping support for specific Platforms

data/lib/yard/fence/hoist.rb

@@ -0,0 +1,9 @@
+if defined?(Yard::Fence) && Yard::Fence.respond_to?(:use_kramdown_gfm!)
+  if Yard::Fence.use_kramdown_gfm!
+    puts "[yard/fence/hoist] Kramdown GFM provider registered"
+  else
+    warn "[yard/fence/hoist] Kramdown GFM provider registration failed"
+  end
+else
+  warn("[yard/fence/hoist] Yard::Fence.use_kramdown_gfm! not available; skipping")
+end

data/lib/yard/fence/version.rb

@@ -3,7 +3,7 @@
 module Yard
   module Fence
     module Version
-      VERSION = "0.2.0"
+      VERSION = "0.4.0"
     end
     VERSION = Version::VERSION
   end

data/lib/yard/fence.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Prepare sanitized copies of Markdown/TXT files in tmp/ for YARD consumption.
+# Prepare sanitized copies of Markdown/TXT files in tmp/yard-fence/ for YARD consumption.
 #
 # Why this exists
 # - YARD treats any `{…}` sequence in extra files (like README.md) as a potential link
@@ -14,8 +14,8 @@
 #   no backslash escapes sprinkled throughout examples).
 # - We need YARD to stop interpreting code-fenced braces as links.
 #
-# Strategy (tmp/ preprocessor)
-# - At doc build time, copy top-level *.md/*.txt into tmp/ and transform only the risky
+# Strategy (tmp/yard-fence/ preprocessor)
+# - At doc build time, copy top-level *.md/*.txt into tmp/yard-fence/ and transform only the risky
 #   brace pairs in contexts YARD misinterprets:
 #   * inside triple‑backtick fenced code blocks
 #   * inside single‑backtick inline code spans
@@ -28,7 +28,7 @@
 #
 # Key lines to see:
 # - Transform to fullwidth:   str.tr('{}', '｛｝')
-#   This replaces ASCII { and } with their fullwidth Unicode counterparts in sanitized tmp files.
+#   This replaces ASCII { and } with their fullwidth Unicode counterparts in sanitized tmp/yard-fence files.
 # - Restore to ASCII (HTML):  out = src.tr('｛｝', '{}')
 #   This runs after docs are generated and rewrites the HTML contents back to normal { and }.
 #
@@ -84,6 +84,7 @@ module Yard
 
     # Escape braces inside inline `code` spans only.
     def sanitize_inline_code(line)
+      # Use $1 because the block parameter (_) is the matched substring, not a MatchData object.
       line.gsub(INLINE_TICK_FENCE) { |_| "`#{fullwidth_braces($1)}`" }
     end
 
@@ -114,10 +115,10 @@ module Yard
       sanitize_fenced_blocks(text)
     end
 
-    # Copy top-level *.md/*.txt into tmp/ with the above sanitization applied.
+    # Copy top-level *.md/*.txt into tmp/yard-fence/ with the above sanitization applied.
     def prepare_tmp_files
       root = Dir.pwd
-      outdir = File.join(root, "tmp")
+      outdir = File.join(root, "tmp", "yard-fence")
       FileUtils.mkdir_p(outdir)
 
       candidates = Dir.glob(File.join(root, GLOB_PATTERN))
@@ -170,11 +171,11 @@ module Yard
     end
   end
 
-  # Execute at load-time so files exist before YARD scans tmp/*.md
+  # Execute at load-time so files exist before YARD scans tmp/yard-fence/*.md
   begin
     Yard::Fence.prepare_tmp_files
   rescue => e
-    warn("Yard::Fence: failed to prepare tmp files: #{e.class}: #{e.message}")
+    warn("Yard::Fence: failed to prepare tmp/yard-fence files: #{e.class}: #{e.message}")
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-fence
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -306,6 +306,7 @@ files:
 - SECURITY.md
 - lib/yard-fence.rb
 - lib/yard/fence.rb
+- lib/yard/fence/hoist.rb
 - lib/yard/fence/kramdown_gfm_document.rb
 - lib/yard/fence/version.rb
 - sig/kramdown.rbs
@@ -315,10 +316,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://yard-fence.galtzo.com/
-  source_code_uri: https://github.com/galtzo-floss/yard-fence/tree/v0.2.0
-  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.2.0/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/yard-fence/tree/v0.4.0
+  changelog_uri: https://github.com/galtzo-floss/yard-fence/blob/v0.4.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/yard-fence/issues
-  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.2.0
+  documentation_uri: https://www.rubydoc.info/gems/yard-fence/0.4.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/yard-fence/wiki
   news_uri: https://www.railsbling.com/tags/yard-fence