Backslash Unescape IDs set via attr_list on toc

[waylan]

Fixes #1493.

[pawamoy]

Thank you @waylan for the super fast fix, and @facelessuser for reviewing ❤️

[pawamoy]

I'm looking into the autorefs warning.

[pawamoy]

OK here's what going wrong:

• when rendering API docs, we enable automatic summaries (summary: true in mkdocs.yml)
• previously this was an Insiders feature, and it was recently made available to everyone, so it's now active in this project too
• when we render the extensions sub-package, we summarize each submodule
• to summarize items, we render the first line of their docstring
• in the case of the admonition module, its first line contains a reference: [rST][]
• since we only render this first line, the reference is unresolved by Python-Markdown itself, and autorefs kicks in (and fails too)

Possible solutions:

• don't use "defered inline references" (not sure what to call them) in docstrings summaries (the first line) and instead put their URL directly within them (so [rST](https://...) instead of [rST][]), or move them lower, into the docstring body
• use pymdownx.snippets to auto-append references at the end of each markdown document (done on the fly, no modification to any file, except maybe to remove all refs from everywhere and gather them in the single auto-appended file, see https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#auto-append-snippets)
• disable auto-summaries

Let me know if I should open a new issue and PR 🙂

[waylan]

The failing test is not related to any changes here so should be handled separately. I'm ignoring it for this PR so a new PR would be appropriate. But thank you for explaining why it was failing.

As an aside, if you are rendering a partial document, then you need to account for reference links and properly render them. IMO there should be no requirement that the document author needs to account for this and alter the way links are formatted. In fact, personally, my preferred style is to always use reference links in documentation. We don't actually have a defined style guide for this project, but it is reasonable to expect that some of your users might.

Yes, I am suggesting that the issue is with mkdocstrings' behavior. I would expect one of two behaviors (possibly both options available via a config option):

1. Reference links are resolved.
2. Links are striped from summaries and only the label text is included.

As far as a temporary fix goes, we should probably either:

1. Disable summaries. But I'm not clear on what they look like so maybe we do want them. I need more info to know.
2. Simply reformat that one link as a quick fix.
3. Consider reworking the text so that the link doesn't appear in the summary. I haven't actually looked at it so this may or may not make sense to do.

But any further discussion should probably happen elsewhere.