🚨 Change documentation to work around rubocop-md bug

pboling · pboling · commit a32db678d32c · 2025-06-01T06:11:05.000+07:00
- rubocop/rubocop-md#28
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -42,6 +42,12 @@ Lint/UnusedBlockArgument:
     - 'vendor/**/*'
     - '**/.irbrc'
 
+# Test if we can turn this back on after upgrading rubocop-md.
+# It is still an open issue, so not expecting it to be fixed.
+# See: https://github.com/rubocop/rubocop-md/issues/28
+Layout/InitialIndentation:
+  Enabled: false
+
 Style/ClassVars:
   Enabled: false
 
diff --git a/README.md b/README.md
@@ -509,29 +509,35 @@ As of v2.0.11, if you need to serialize the parsed result, you can!
 
 There are two ways to do this, globally, or discretely.  The discrete way is recommended.
 
-1. Globally configure `SnakyHash::StringKeyed` to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails):
+##### Global Serialization Config
 
-    ```ruby
+Globally configure `SnakyHash::StringKeyed` to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).
+
+```ruby
 SnakyHash::StringKeyed.class_eval do
   extend SnakyHash::Serializer
 end
-    ```
+```
+
+##### Discrete Serialization Config
 
-2. Discretely configure a custom Snaky Hash class to use the serializer:
+Discretely configure a custom Snaky Hash class to use the serializer.
 
-    ```ruby
+```ruby
 class MySnakyHash < SnakyHash::StringKeyed
   # Give this hash class `dump` and `load` abilities!
   extend SnakyHash::Serializer
 end
 
-    # And tell your client to use the custom class in each call:
+# And tell your client to use the custom class in each call:
 client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2")
 token = client.get_token({snaky_hash_klass: MySnakyHash})
-    ```
+```
 
 ##### Serialization Extensions
 
+These extensions work regardless of whether you used the global or discrete config above.
+
 There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6.
 They are likely not needed if you are on a newer Ruby.
 See `response_spec.rb` if you need to study the hacks for older Rubies.
@@ -791,7 +797,7 @@ For example:
 spec.add_dependency("oauth2", "~> 2.0")
 ```
 
-See [CHANGELOG.md][📌changelog] for list of releases.
+See [CHANGELOG.md][📌changelog] for a list of releases.
 
 ## 📄 License
 
diff --git a/docs/OAuth2.html b/docs/OAuth2.html
@@ -326,7 +326,7 @@ <h3 class="signature first" id="configure-class_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/AccessToken.html b/docs/OAuth2/AccessToken.html
@@ -3069,7 +3069,7 @@ <h3 class="signature " id="to_hash-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Authenticator.html b/docs/OAuth2/Authenticator.html
@@ -631,7 +631,7 @@ <h3 class="signature first" id="apply-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Client.html b/docs/OAuth2/Client.html
@@ -2651,7 +2651,7 @@ <h3 class="signature " id="token_url-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Error.html b/docs/OAuth2/Error.html
@@ -518,7 +518,7 @@ <h3 class="signature " id="response-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/FilteredAttributes.html b/docs/OAuth2/FilteredAttributes.html
@@ -268,7 +268,7 @@ <h3 class="signature first" id="inspect-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/FilteredAttributes/ClassMethods.html b/docs/OAuth2/FilteredAttributes/ClassMethods.html
@@ -218,7 +218,7 @@ <h3 class="signature " id="filtered_attributes-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Response.html b/docs/OAuth2/Response.html
@@ -1619,7 +1619,7 @@ <h3 class="signature " id="status-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy.html b/docs/OAuth2/Strategy.html
@@ -107,7 +107,7 @@ <h2>Defined Under Namespace</h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy/Assertion.html b/docs/OAuth2/Strategy/Assertion.html
@@ -481,7 +481,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy/AuthCode.html b/docs/OAuth2/Strategy/AuthCode.html
@@ -469,7 +469,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy/Base.html b/docs/OAuth2/Strategy/Base.html
@@ -195,7 +195,7 @@ <h3 class="signature first" id="initialize-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy/ClientCredentials.html b/docs/OAuth2/Strategy/ClientCredentials.html
@@ -343,7 +343,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy/Implicit.html b/docs/OAuth2/Strategy/Implicit.html
@@ -410,7 +410,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Strategy/Password.html b/docs/OAuth2/Strategy/Password.html
@@ -364,7 +364,7 @@ <h3 class="signature " id="get_token-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/OAuth2/Version.html b/docs/OAuth2/Version.html
@@ -111,7 +111,7 @@ <h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/_index.html b/docs/_index.html
@@ -303,7 +303,7 @@ <h2>Namespace Listing A-Z</h2>
 </div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:09 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html
@@ -836,7 +836,7 @@ <h2 id="001---2010-04-22-tag">
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.CITATION.html b/docs/file.CITATION.html
@@ -85,7 +85,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.CODE_OF_CONDUCT.html b/docs/file.CODE_OF_CONDUCT.html
@@ -192,7 +192,7 @@ <h2 id="attribution">Attribution</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.CONTRIBUTING.html b/docs/file.CONTRIBUTING.html
@@ -195,7 +195,7 @@ <h3 id="to-release-a-new-version">To release a new version:</h3>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html
@@ -60,7 +60,7 @@
       <div id="content"><div id='filecontents'>MIT License<br><br>Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc.<br>Copyright (c) 2017 - 2025 Peter H. Boling, of RailsBling.com, and OAuth2 contributors<br><br>Permission is hereby granted, free of charge, to any person obtaining a copy<br>of this software and associated documentation files (the "Software"), to deal<br>in the Software without restriction, including without limitation the rights<br>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell<br>copies of the Software, and to permit persons to whom the Software is<br>furnished to do so, subject to the following conditions:<br><br>The above copyright notice and this permission notice shall be included in all<br>copies or substantial portions of the Software.<br><br>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR<br>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,<br>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE<br>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER<br>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE<br>SOFTWARE.</div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.README.html b/docs/file.README.html
@@ -711,32 +711,33 @@ <h4 id="serialization">Serialization</h4>
 
 <p>There are two ways to do this, globally, or discretely.  The discrete way is recommended.</p>
 
-<ol>
-  <li>
-    <p>Globally configure <code>SnakyHash::StringKeyed</code> to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails):</p>
+<h5 id="global-serialization-config">Global Serialization Config</h5>
+
+<p>Globally configure <code>SnakyHash::StringKeyed</code> to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).</p>
 
-    <pre class="code language-ruby"><code class="language-ruby">SnakyHash::StringKeyed.class_eval do
+<pre class="code language-ruby"><code class="language-ruby">SnakyHash::StringKeyed.class_eval do
   extend SnakyHash::Serializer
 end
 </code></pre>
-  </li>
-  <li>
-    <p>Discretely configure a custom Snaky Hash class to use the serializer:</p>
 
-    <pre class="code language-ruby"><code class="language-ruby">class MySnakyHash &lt; SnakyHash::StringKeyed
+<h5 id="discrete-serialization-config">Discrete Serialization Config</h5>
+
+<p>Discretely configure a custom Snaky Hash class to use the serializer.</p>
+
+<pre class="code language-ruby"><code class="language-ruby">class MySnakyHash &lt; SnakyHash::StringKeyed
   # Give this hash class `dump` and `load` abilities!
   extend SnakyHash::Serializer
 end
 
- # And tell your client to use the custom class in each call:
+# And tell your client to use the custom class in each call:
 client = OAuth2::Client.new(&quot;client_id&quot;, &quot;client_secret&quot;, site: &quot;https://example.org/oauth2&quot;)
 token = client.get_token({snaky_hash_klass: MySnakyHash})
 </code></pre>
-  </li>
-</ol>
 
 <h5 id="serialization-extensions">Serialization Extensions</h5>
 
+<p>These extensions work regardless of whether you used the global or discrete config above.</p>
+
 <p>There are a few hacks you may need in your class to support Ruby &lt; 2.4.2 or &lt; 2.6.<br>
 They are likely not needed if you are on a newer Ruby.<br>
 See <code>response_spec.rb</code> if you need to study the hacks for older Rubies.</p>
@@ -996,7 +997,7 @@ <h3 id="-is-platform-support-part-of-the-public-api">📌 Is “Platform Support
 <pre class="code language-ruby"><code class="language-ruby">spec.add_dependency(&quot;oauth2&quot;, &quot;~&gt; 2.0&quot;)
 </code></pre>
 
-<p>See <a href="file.CHANGELOG.html" title="CHANGELOG.md">CHANGELOG.md</a> for list of releases.</p>
+<p>See <a href="file.CHANGELOG.html" title="CHANGELOG.md">CHANGELOG.md</a> for a list of releases.</p>
 
 <h2 id="-license">📄 License</h2>
 
@@ -1043,7 +1044,7 @@ <h2 id="-one-more-thing">🤑 One more thing</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:09 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/file.SECURITY.html b/docs/file.SECURITY.html
@@ -113,7 +113,7 @@ <h2 id="enterprise-support">Enterprise Support</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:10 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/index.html b/docs/index.html
@@ -711,32 +711,33 @@ <h4 id="serialization">Serialization</h4>
 
 <p>There are two ways to do this, globally, or discretely.  The discrete way is recommended.</p>
 
-<ol>
-  <li>
-    <p>Globally configure <code>SnakyHash::StringKeyed</code> to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails):</p>
+<h5 id="global-serialization-config">Global Serialization Config</h5>
+
+<p>Globally configure <code>SnakyHash::StringKeyed</code> to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).</p>
 
-    <pre class="code language-ruby"><code class="language-ruby">SnakyHash::StringKeyed.class_eval do
+<pre class="code language-ruby"><code class="language-ruby">SnakyHash::StringKeyed.class_eval do
   extend SnakyHash::Serializer
 end
 </code></pre>
-  </li>
-  <li>
-    <p>Discretely configure a custom Snaky Hash class to use the serializer:</p>
 
-    <pre class="code language-ruby"><code class="language-ruby">class MySnakyHash &lt; SnakyHash::StringKeyed
+<h5 id="discrete-serialization-config">Discrete Serialization Config</h5>
+
+<p>Discretely configure a custom Snaky Hash class to use the serializer.</p>
+
+<pre class="code language-ruby"><code class="language-ruby">class MySnakyHash &lt; SnakyHash::StringKeyed
   # Give this hash class `dump` and `load` abilities!
   extend SnakyHash::Serializer
 end
 
- # And tell your client to use the custom class in each call:
+# And tell your client to use the custom class in each call:
 client = OAuth2::Client.new(&quot;client_id&quot;, &quot;client_secret&quot;, site: &quot;https://example.org/oauth2&quot;)
 token = client.get_token({snaky_hash_klass: MySnakyHash})
 </code></pre>
-  </li>
-</ol>
 
 <h5 id="serialization-extensions">Serialization Extensions</h5>
 
+<p>These extensions work regardless of whether you used the global or discrete config above.</p>
+
 <p>There are a few hacks you may need in your class to support Ruby &lt; 2.4.2 or &lt; 2.6.<br>
 They are likely not needed if you are on a newer Ruby.<br>
 See <code>response_spec.rb</code> if you need to study the hacks for older Rubies.</p>
@@ -996,7 +997,7 @@ <h3 id="-is-platform-support-part-of-the-public-api">📌 Is “Platform Support
 <pre class="code language-ruby"><code class="language-ruby">spec.add_dependency(&quot;oauth2&quot;, &quot;~&gt; 2.0&quot;)
 </code></pre>
 
-<p>See <a href="file.CHANGELOG.html" title="CHANGELOG.md">CHANGELOG.md</a> for list of releases.</p>
+<p>See <a href="file.CHANGELOG.html" title="CHANGELOG.md">CHANGELOG.md</a> for a list of releases.</p>
 
 <h2 id="-license">📄 License</h2>
 
@@ -1043,7 +1044,7 @@ <h2 id="-one-more-thing">🤑 One more thing</h2>
 </div></div>
 
       <div id="footer">
-  Generated on Sun Jun  1 05:31:39 2025 by
+  Generated on Sun Jun  1 06:10:09 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.3).
 </div>
diff --git a/docs/top-level-namespace.html b/docs/top-level-namespace.html
