Repository: mne-tools/mne-bids-pipeline

Issue:
DOC: Website <->README sync
Following @hoechenberger's PRs I think our README.md (which ends up on PyPI) looks nicer / does better advertising than our docs landing page does

| https://pypi.org/project/mne-bids-pipeline/#description | https://mne.tools/mne-bids-pipeline/1.0/index.html |
| -- | -- |
| ![Screenshot from 2022-12-08 13-01-47](https://user-images.githubusercontent.com/2365790/206529981-f1808ad5-49bf-4236-b904-ff72f9e12e70.png) | ![Screenshot from 2022-12-08 13-01-53](https://user-images.githubusercontent.com/2365790/206530007-2bbf52c3-229a-47bf-b2c9-b23812fdc977.png) |

I propose that we should add the tag line and bullet points from the README.md to the landing page for mne-bids-pipeline, and also double check that our project description matches. This would also make it a bit more like MNE-Python, where our landing page tries to quickly convey "This package can do a lot of cool stuff that you want!".

I propose that we should modify `build_docs.sh` to have a `gen_index.py` that takes the bullet points of README.md and pastes them into the `index.md` for the website.

@hoechenberger @drammock WDYT?


Discussion:
If it's possible to convert the README to .rst format and still have it look nice on PyPI, then this becomes a very straightforward rst `.. include::` in the docs homepage, with `:start-after:` and/or `:end-before:` args.

...oh wait.  this isn't sphinx.  🌩️#️⃣👎🏻‼️  
Yes someday maybe we'll move to Sphinx :)

But for now, WDYT about the contents -- do you agree the landing page should advertise the features more? And if so, should this be synced with README.md?
... and I think there is an equivalent way I found already to include parts of markdown files. Agreed that's better than writing a `.py` to do it
yes agreed that the README is currently better than the landing page, and they should be in sync.
I am working on expanding the introductory docs anyway, please be give me a few more days 🥵
I think this one can be closed for now, thanks to #693 and soon #698 
My goal was to deduplicate actually, but it's still copy-paste. I'd rather use the include-lines stuff so we don't have to *manually* keep them in sync...
But that's not possible because in the rendered docs we use Twemoji and these are not available in plain Markdown...
In Sphinx it's easy to hook into the `rst-read` event where you can arbitrarily change the contents. We could look to see if something similar is available in `mkdocs` and we can just `text.replace(md, te) for md, te in md_te_mapping.items()` and keep the `md_te_mapping` dict up to date...

Resolving patch:
diff --git a/docs/hooks.py b/docs/hooks.py
--- a/docs/hooks.py
+++ b/docs/hooks.py
@@ -2,6 +2,8 @@
 from typing import Dict, Any
 
 from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.pages import Page
+from mkdocs.structure.files import Files
 
 logger = logging.getLogger("mkdocs")
 
@@ -22,3 +24,29 @@ def on_template_context(
         now = context["build_date_utc"].strftime("%Y/%m/%d")
         config.copyright = f"{config.copyright}, last updated {now}"
         logger.info(f"Updated copyright to {config.copyright}")
+
+
+_EMOJI_MAP = {
+    "🏆": ":trophy:",
+    "🛠️": ":tools:",
+    "📘": ":blue_book:",
+    "🧑‍🤝‍🧑": ":people_holding_hands_tone1:",
+    "💻": ":computer:",
+    "🆘": ":sos:",
+    "👣": ":footprints:",
+    "⏩": ":fast_forward:",
+    "⏏️": ":eject:",
+    "☁️": ":cloud:",
+}
+
+
+def on_page_markdown(
+    markdown: str,
+    page: Page,
+    config: MkDocsConfig,
+    files: Files,
+) -> str:
+    if page.file.name == "index" and page.title == "Home":
+        for rd, md in _EMOJI_MAP.items():
+            markdown = markdown.replace(rd, md)
+    return markdown


Test patch: