[Fix #9150] Escape special chars in docs

[wcmonty]

This partially resolves #9150. See similar PR at rubocop/rubocop-ast#187. This PR escapes the special characters { and } when they aren't intended to be interpolated. It does not fully resolve the issue, because older tags are still included when the docs are generated. Those tags are configured at https://github.com/rubocop/docs.rubocop.org/blob/master/antora-playbook.yml.

# Let's generate HTML docs on master
# We will see the same warnings we see in docs.rubocop.org
rubocop-fork git:(master) $ git co master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
rubocop-fork git:(master) $ asciidoctor -a attribute-missing=warn docs/modules/ROOT/pages/cops_naming.adoc -o cops_naming-master.html
asciidoctor: WARNING: skipping reference to missing attribute: 1
rubocop-fork git:(master) $ asciidoctor -a attribute-missing=warn docs/modules/ROOT/pages/cops_style.adoc -o cops_style-master.html
asciidoctor: WARNING: skipping reference to missing attribute: 3
asciidoctor: WARNING: skipping reference to missing attribute: word
asciidoctor: WARNING: skipping reference to missing attribute: word
asciidoctor: WARNING: skipping reference to missing attribute: word
rubocop-fork git:(master) $ asciidoctor -a attribute-missing=warn docs/modules/ROOT/pages/development.adoc -o development-master.html
asciidoctor: WARNING: skipping reference to missing attribute: foo
asciidoctor: WARNING: skipping reference to missing attribute: foo
asciidoctor: WARNING: skipping reference to missing attribute: foo

# Now let's run on the feature branch
rubocop-fork git:(master) $ git co wm/escape_special_chars_in_docs
switched to branch 'wm/escape_special_chars_in_docs'
rubocop-fork git:(wm/escape_special_chars_in_docs) $ asciidoctor -a attribute-missing=warn docs/modules/ROOT/pages/cops_naming.adoc -o cops_naming-escaped.html
rubocop-fork git:(wm/escape_special_chars_in_docs) $ asciidoctor -a attribute-missing=warn docs/modules/ROOT/pages/cops_style.adoc -o cops_style-escaped.html
rubocop-fork git:(wm/escape_special_chars_in_docs) $ asciidoctor -a attribute-missing=warn docs/modules/ROOT/pages/development.adoc -o development-escaped.html

# Here we make sure that the generated files are the same, except for the timestamps
rubocop-fork git:(wm/escape_special_chars_in_docs) $ diff cops_naming-master.html cops_naming-escaped.html
2343c2343
< Last updated 2021-07-02 13:24:59 -0400
---
> Last updated 2021-07-02 13:27:01 -0400
rubocop-fork git:(wm/escape_special_chars_in_docs) $ diff cops_style-master.html cops_style-escaped.html
20675c20675
< Last updated 2021-07-02 13:24:59 -0400
---
> Last updated 2021-07-02 13:27:01 -0400
rubocop-fork git:(wm/escape_special_chars_in_docs) $ diff development-master.html development-escaped.html
991c991
< Last updated 2021-07-02 13:24:59 -0400
---
> Last updated 2021-07-02 13:27:01 -0400

---

Note I'm marking Added tests and Ran "bundle exec rake default". as done, because these changes just impact docs and not the codebase.

Before submitting the PR make sure the following are checked:

• The PR relates to only one subject with a clear title and description in grammatically correct, complete sentences.
• Wrote good commit messages.
• Commit message starts with [Fix #issue-number] (if the related issue exists).
• Feature branch is up-to-date with master (if not - rebase it).
• Squashed related commits together.
• Added tests.
• Ran bundle exec rake default. It executes all tests and runs RuboCop on its own code.
• Added an entry (file) to the changelog folder named {change_type}_{change_description}.md if the new code introduces user-observable changes. See changelog entry format for details.

[dvandersluis]

Looks to me like there's a bug in how the adocs are automatically generated? The fixes you made are good but will be overwritten the next time docs are generated because all the cop pages are generated automatically.

Also, this probably would need to be done/fixed for every single rubocop extension library (without the rubocop org at least).

[wcmonty]

Ah, I didn't realize that the adocs were being generated. Let me take a look to see if I can fix the root cause.