Encourage R users to check out animovement

[niksirbi]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Documentation

Why is this PR needed?

Closes #305

What does this PR do?

Adds a "tip" admonition to the README and the website homepage. Sadly I had to duplicate the text in both places, because the syntax for creating admonition boxes is different in GitHub-flavored vs myst-markdown. We could do away with the duplication if we went for simpler rendering options, but I like how the admonitions look.

How has this PR been tested?

Local docs build.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.76%. Comparing base (7813e7c) to head (c7356dc).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #335   +/-   ##
=======================================
  Coverage   99.76%   99.76%           
=======================================
  Files          14       14           
  Lines         846      846           
=======================================
  Hits          844      844           
  Misses          2        2           

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

[sfmig]

LGTM! nice shoutout ⭐

I was thinking about how we could avoid the duplication and was wondering if a script that converts between myst and github-flavoured markdown admonitions may be helpful. We already have two admonition duplicates, if we expect it to grow it may be worth it.

Maybe one way could be we programmatically generate some of the snippets .md files by searching for GFM admonitions in the README file. I had a quick go generating a converter script, but feel free to ditch if too complicated.

import argparse
import re


def extract_gfm_admonitions_as_snippets(gfm_text):
    # Regex pattern to match GFM admonition structure
    matches = re.findall(r"^>\s?(.*)", gfm_text, re.MULTILINE)

    if not matches:
        return "No GitHub Markdown admonitions found."

    # Extract admonition type and content
    admonition_dict = {}
    for m_i, m in enumerate(matches):
        if m.startswith("[!"):
            admonition_dict[m.strip("[!]")] = matches[m_i + 1]

    # Convert GFM admonitions to MyST format
    for admonition_type, content in admonition_dict.items():
        # apply MyST formatting
        myst_admonition = (
            f"::{{admonition}} {admonition_type.capitalize()}\n"
            f":class: {admonition_type}\n"
            f"{content}\n:::"
        )

        # write to file
        with open(f"snippets/{admonition_type}.md", "w") as file:
            file.write(myst_admonition)


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("gfm_file", help="Path to GFM markdown file")

    args = parser.parse_args()

    # read a GFM markdown file
    with open(args.gfm_file) as file:
        gfm_text = file.read()

    # extract GFM admonitions as MyST-flavoured .md snippets
    myst_text = extract_gfm_admonitions_as_snippets(gfm_text)
    print(myst_text)

[niksirbi]

Hey @sfmig, thanks for sending me down a 🐰 🕳️

I ended up writing such a script (using yours as a starting points). Not sure it's worth it, since for the sake of 2 admonitions we now have to maintain an entire script, bit I lean towards using the script anyway. My reasoning is that in the future we may build upon it to do some more intelligent parsing from README.md to index.md, in a way that further reduces duplication (not just across admonitions).

[niksirbi]

@ not really needed in front of echo, because of the @ECHO OFF at the top of make.bat.

[sfmig]

I like it! You took it to the next level! 🚀

we now have to maintain an entire script

True! But maybe maintaining a script is better than remembering both sources of text need to be in sync?

we may build upon it to do some more intelligent parsing from README.md to index.md, in a way that further reduces duplication.

That sounds like a nice idea.

[lochhh]

Quality Gate passed

Issues 1 New issue

Just a reminder here to check this

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[niksirbi]

Thanks both! I've now refactored the conversion script to reduce its cognitive complexity. I think this is now ready to merge.