✨ NEW: Port abbr plugin (executablebooks#14)

[jessicah]

No description provided.

[welcome]

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.

Welcome to the EBP community! 🎉

[jessicah]

Hmm, pre-commit seems broken due to PyCQA/isort#2077? I certainly can't run it.

[chrisjsewell]

Thanks @jessicah, could you perhaps add some more test cases, e.g. interaction with other syntax elements: abbr definitions in lists, abbr references in link texts, ...

Looking at this now, one issue related to myst-parser I'd note, is that the extension is doing a "look-ahead" parse to find all the abbreviation definitions.
This is pain in relation to nested parsing. For example:

```{note}
*[HTML]: HyperText Markup Language

HTML
```

HTML

Here, in MyST-Parser, the outer HTML would not be converted to an abbreviation, because at that point in the rendering, the inner contents of the note have not yet been parsed.

The "ideal" solution may be, to have the markdown-it plugin collect all the abbreviation definitions, but not do the replacement of the text.
Then, after the text has been fully converted to sphinx/docutils nodes, and all the abbr definitions have been collected, run a sphinx/docutils transform to do all the find/replace replacements

[jessicah]

@chrisjsewell hmm, that's how the original plugin does the replacements, it's basically a 1:1 translation of the source, just some janky translation of their regex loop.

I don't really know enough to be able to adapt to a nested parsing model; I pretty much relied on comparing an existing JS <-> Python extension... if you have some guidance, that would help!

[codecov]

Codecov Report

❌ Patch coverage is 88.46154% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.43%. Comparing base (4601e15) to head (838f199).
⚠️ Report is 42 commits behind head on master.

Files with missing lines	Patch %	Lines
mdit_py_plugins/abbr/index.py	88.34%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #63      +/-   ##
==========================================
- Coverage   92.67%   92.43%   -0.25%     
==========================================
  Files          29       32       +3     
  Lines        1679     1784     +105     
==========================================
+ Hits         1556     1649      +93     
- Misses        123      135      +12     

Flag	Coverage Δ
pytests	92.43% <88.46%> (-0.25%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chrisjsewell]

if you have some guidance, that would help!

I think just for now, if you could add in an option to not make the replacements (i.e. just extract the definitions).
Then we have the option to do this on the myst-parser side.

def abbr_plugin(md: MarkdownIt, replace = True):
    """Plugin ported from
    `markdown-it-abbr <https://github.com/markdown-it/markdown-it-abbr>`__.

    .. code-block:: md
            *[HTML]: HyperText Markup Language
    """

    md.block.ruler.before(
        "reference", "abbr_def", abbr_def, {"alt": ["paragraph", "reference"]}
    )
    if replace:
        md.core.ruler.after("linkify", "abbr_replace", abbr_replace)

and yeh also if you can add some more tests