Split README into snippets to enable multilingual assemble

.github/workflows/assemble-readme.yml

@@ -0,0 +1,34 @@
+# This workflow will generate README files based on the doc snippets.
+
+name: Assemble Multilingual README
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/snippets/markdown/readme/'
+      - 'docs/pipelines/README.md.template'
+      - 'docs/pipelines/generate_readme.py'
+  workflow_dispatch:
+
+jobs:
+  assemble-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Run script and get output files
+        run: |
+          python docs/pipelines/generate_readme.py
+          mv docs/pipelines/README*.md ./
+          git add ./README*.md
+          git commit -m ""
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v5
+        with:
+          commit-message: Assemble README files from snippets
+          title: Automatic README update
+          body: Assemble README files from snippets
+          branch: assemble-readme

docs/pipelines/README.md.template

@@ -0,0 +1,19 @@
+{!docs/snippets/markdown/readme/0-opener.<lang>.md!}
+
+{!docs/snippets/markdown/readme/0a-language-badges.md!}
+
+{!docs/snippets/markdown/readme/0b-status-badges.md!}
+
+{!docs/snippets/markdown/readme/0c-intro.<lang>.md!}
+
+{!docs/snippets/markdown/readme/1-live-demos.<lang>.md!}
+
+{!docs/snippets/markdown/readme/2-features.<lang>.md!}
+
+{!docs/snippets/markdown/readme/3-install.md!}
+
+{!docs/snippets/markdown/readme/4-resources.<lang>.md!}
+
+{!docs/snippets/markdown/readme/5-announcements.<lang>.md!}
+
+{!docs/snippets/markdown/readme/6-remarks.<lang>.md!}

docs/pipelines/generate_readme.py

@@ -0,0 +1,28 @@
+import os
+from markdown_include.include import MarkdownInclude, IncludePreprocessor
+
+README_TEMPLATE_PATH = os.path.join(os.path.dirname(__file__), "README.md.template")
+LANGUAGE_PLACEHOLDER = "<lang>"
+LANGS = ["en", "zh"]
+DEFAULT_LANG = "en"
+
+
+def main():
+    with open(README_TEMPLATE_PATH, "r") as f:
+        template = f.read()
+    include = MarkdownInclude()
+    preprocessor = IncludePreprocessor(template, include.getConfigs())
+
+    for lang in LANGS:
+        filename = "README.md" if lang == DEFAULT_LANG else f"README.{lang}.md"
+        readme_path = os.path.join(os.path.dirname(__file__), filename)
+        transformed = "\n".join(
+            preprocessor.run(template.replace(LANGUAGE_PLACEHOLDER, lang).split("\n"))
+        )
+        with open(readme_path, "w") as f:
+            f.write(transformed)
+            print(f"Generated {readme_path} for language {lang}.")
+
+
+if __name__ == "__main__":
+    main()

docs/snippets/markdown/readme/0-opener.en.md

@@ -0,0 +1,5 @@
+![Hover](https://raw.githubusercontent.com/phurwicz/hover/main/docs/images/hover-logo-title.png)
+
+> Explore and label on a map of your data.
+>
+> Get enough to feed your model in no time.

docs/snippets/markdown/readme/0-opener.zh.md

@@ -0,0 +1,3 @@
+![Hover](https://raw.githubusercontent.com/phurwicz/hover/main/docs/images/hover-logo-title.png)
+
+> 通过向量降维, 极速探索和批量标注数据, 并用作模型训练或其它用途.

docs/snippets/markdown/readme/0a-language-badges.md

@@ -0,0 +1,2 @@
+[![en](https://img.shields.io/badge/lang-en-green.svg)](https://github.com/phurwicz/hover/blob/main/README.md)
+[![zh](https://img.shields.io/badge/语言-中文-green.svg)](https://github.com/phurwicz/hover/blob/main/README.zh.md)

docs/snippets/markdown/readme/0b-status-badges.md

@@ -0,0 +1,7 @@
+[![PyPI Version](https://img.shields.io/pypi/v/hover?logo=pypi&logoColor=white)](https://pypi.org/project/hover/)
+[![Conda Version](https://img.shields.io/conda/vn/conda-forge/hover)](https://github.com/conda-forge/hover-feedstock)
+![Downloads](https://static.pepy.tech/personalized-badge/hover?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=pypi%20downloads)
+![Main Build Status](https://img.shields.io/github/actions/workflow/status/phurwicz/hover/cross-os-source-test.yml?branch=main&label=main&logo=github)
+![Nightly Build Status](https://img.shields.io/github/actions/workflow/status/phurwicz/hover/quick-source-test.yml?branch=nightly&label=nightly&logo=github)
+![Codacy Grade](https://img.shields.io/codacy/grade/689827d9077b43ac8721c7658d122d1a?logo=codacy&logoColor=white)
+![Codacy Coverage](https://img.shields.io/codacy/coverage/689827d9077b43ac8721c7658d122d1a/main?logo=codacy&logoColor=white)

docs/snippets/markdown/readme/0c-intro.en.md

@@ -0,0 +1,8 @@
+`hover` is a tool for mass-labeling data points that can be represented by vectors.
+
+-   Labeling is as easy as coloring a scatter plot.
+-   Hover your mouse and lasso-select to inspect any cluster.
+-   Use a variety of widgets to narrow down further.
+-   Enter a suitable label and hit "Apply"!
+
+![GIF Demo](https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.5.0/trailer-short.gif)

docs/snippets/markdown/readme/0c-intro.zh.md

@@ -0,0 +1,8 @@
+`hover` 是一个批量标注数据的工具, 只需数据能被向量表示.
+
+-   标注过程很简单, 如同给散点图上色.
+-   通过移动鼠标和框选, 来观察数据(在降维后的)点簇.
+-   使用小工具(如搜索/过滤/规则/主动学习)来提升精度.
+-   输入合适的标签, 并点击"Apply"按钮, 即可标注!
+
+![GIF Demo](https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.5.0/trailer-short.gif)

docs/snippets/markdown/readme/1-live-demos.en.md

@@ -0,0 +1,9 @@
+## :rocket: Live Demos
+
+### [**With code**](https://phurwicz.github.io/hover/pages/tutorial/t0-quickstart/)
+
+-   edit & run code in your browser to get a labeling interface, with guides along the way.
+
+### [**Without code**](https://mybinder.org/v2/gh/phurwicz/hover-binder/master?urlpath=/proxy/5006/app-simple-annotator)
+
+-   go directly to an example labeling interface hosted on Binder.

docs/snippets/markdown/readme/1-live-demos.zh.md

@@ -0,0 +1,9 @@
+## :rocket: 在线演示
+
+### [**Notebook教程**](https://phurwicz.github.io/hover/pages/tutorial/t0-quickstart/)
+
+-   查看含代码的教程, 可在浏览器中编辑和运行, 无需安装依赖.
+
+### [**示例标注界面**](https://mybinder.org/v2/gh/phurwicz/hover-binder/master?urlpath=/proxy/5006/app-simple-annotator)
+
+-   跳过所有代码, 进入托管在Binder上的标注界面.

docs/snippets/markdown/readme/2-features.en.md

@@ -0,0 +1,63 @@
+## :sparkles: Features
+
+> **It's fast because it labels data in bulk.**
+
+:telescope: A semantic scatter plot of your data for labeling, equipped with
+
+<details open>
+  <summary> <b>Tooltip</b> for each point on mouse hover </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/image-tooltip.gif">
+</details>
+
+<details>
+  <summary> Table view for <b>inspecting selected</b> points </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/selection-table.gif">
+</details>
+
+<details>
+  <summary> Toggle buttons that clearly <b>distinguish data subsets</b> </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/subset-toggle.gif">
+</details>
+
+<details>
+  <summary> <b>Search</b> widgets for ad-hoc data highlight </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/text-search-response.gif">
+</details>
+
+> **It's accurate because multiple components work together.**
+
+:microscope: Supplementary views to use in conjunction with the annotator, including
+
+<details>
+  <summary> `Finder`: <b>filter</b> data by search criteria</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/finder-filter.gif">
+</details>
+
+<details>
+  <summary> `SoftLabel`: <b>active learning</b> by in-the-loop model prediction score</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/active-learning.gif">
+</details>
+
+<details>
+  <summary> `Snorkel`: <b>custom functions</b> for labeling and filtering</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/labeling-function.gif">
+</details>
+
+> **It's flexible (and fun!) because the process never gets old.**
+
+:toolbox: Additional tools and options that allow you to
+
+<details>
+  <summary> Go to <b>higher dimensions</b> (3D? 4D?) and choose your xy-axes </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/change-axes.gif">
+</details>
+
+<details>
+  <summary> <b>Consecutively select</b> across areas, dimensions, and views</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/keep-selecting.gif">
+</details>
+
+<details>
+  <summary> <b>Kick outliers</b> and <b>fix mistakes</b></summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/evict-and-patch.gif">
+</details>

docs/snippets/markdown/readme/2-features.zh.md

@@ -0,0 +1,57 @@
+## :sparkles: 具体功能
+
+:telescope: 将向量降维得到二维数据散点图, 并配有
+
+<details open>
+  <summary> <b>提示框</b> 来显示具体数据内容 </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/image-tooltip.gif">
+</details>
+
+<details>
+  <summary> 表格来 <b>批量检视</b> 选中的数据 </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/selection-table.gif">
+</details>
+
+<details>
+  <summary> 切换按钮来 <b>区分数据子集</b> </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/subset-toggle.gif">
+</details>
+
+<details>
+  <summary> <b>文本/正则匹配</b> 来定向搜寻数据 </summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/text-search-response.gif">
+</details>
+
+:microscope: 与标注界面同步的辅助模式
+
+<details>
+  <summary> `Finder`: 以匹配条件来 <b>过滤</b> 选中的数据</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/finder-filter.gif">
+</details>
+
+<details>
+  <summary> `SoftLabel`: <b>主动学习</b> 用模型打分过滤选中的数据</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/active-learning.gif">
+</details>
+
+<details>
+  <summary> `Snorkel`: <b>自定义函数</b> 来过滤数据或直接打标</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/labeling-function.gif">
+</details>
+
+:toolbox: 更多的补充工具
+
+<details>
+  <summary> 降维时保留 <b>更多维度</b> (3D? 4D?) 并动态选择观察的平面</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/change-axes.gif">
+</details>
+
+<details>
+  <summary> 跨界面/跨维度地进行 <b>持续选取/反选</b> 以达到更高精度</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/keep-selecting.gif">
+</details>
+
+<details>
+  <summary> <b>剔除</b>选中数据中的异类 以及 <b>修订</b>发现的误标</summary>
+  <img src="https://raw.githubusercontent.com/phurwicz/hover-gallery/main/0.7.0/evict-and-patch.gif">
+</details>

docs/snippets/markdown/readme/3-install.md

@@ -0,0 +1,9 @@
+## :package: Install
+
+> Python: 3.8+
+>
+> OS: Linux & Mac & Windows
+
+PyPI: `pip install hover`
+
+Conda: `conda install -c conda-forge hover`

docs/snippets/markdown/readme/4-resources.en.md

@@ -0,0 +1,6 @@
+## :book: Resources
+
+-   [Tutorials](https://phurwicz.github.io/hover/pages/tutorial/t0-quickstart/)
+-   [Binder repo](https://github.com/phurwicz/hover-binder)
+-   [Changelog](https://github.com/phurwicz/hover/blob/main/CHANGELOG.md)
+-   [Documentation](https://phurwicz.github.io/hover/)

docs/snippets/markdown/readme/4-resources.zh.md

@@ -0,0 +1,6 @@
+## :book: 资料
+
+-   [教程](https://phurwicz.github.io/hover/pages/tutorial/t0-quickstart/)
+-   [Binder仓库](https://github.com/phurwicz/hover-binder)
+-   [版本说明](https://github.com/phurwicz/hover/blob/main/CHANGELOG.md)
+-   [文档](https://phurwicz.github.io/hover/)

docs/snippets/markdown/readme/5-announcements.en.md

@@ -0,0 +1,3 @@
+## :flags: Announcements
+
+-   **Jan 21, 2023** version 0.8.0 is now available. Check out the [changelog](https://github.com/phurwicz/hover/blob/main/CHANGELOG.md) for details :partying_face:.

docs/snippets/markdown/readme/5-announcements.zh.md

@@ -0,0 +1,3 @@
+## :flags: 新动态
+
+-   **Jan 21, 2023** 新版本 0.8.0 已就绪, 可查看 [changelog](https://github.com/phurwicz/hover/blob/main/CHANGELOG.md) 获悉详情 :partying_face:.

docs/snippets/markdown/readme/6-remarks.en.md

@@ -0,0 +1,28 @@
+## :bell: Remarks
+
+### Shoutouts
+
+-   Thanks to [`Bokeh`](https://bokeh.org) because `hover` would not exist without linked plots and callbacks, or be nearly as good without embeddable server apps.
+-   Thanks to [Philip Vollet](https://de.linkedin.com/in/philipvollet) for sharing `hover` with the community even when it was really green.
+
+### Contributing
+
+-   All feedbacks are welcome, **especially what you find lacking and want it fixed!**
+-   `./requirements-dev.txt` lists required packages for development.
+-   Pull requests are advised to use a superset of the pre-commit hooks listed in [.pre-commit-config.yaml](https://github.com/phurwicz/hover/blob/main/.pre-commit-config.yaml).
+
+### Citation
+
+If you have found `hover` useful to your work, please [let us know](https://github.com/phurwicz/hover/discussions) :hugs:
+
+```tex
+@misc{hover,
+  title={{hover}: label data at scale},
+  url={https://github.com/phurwicz/hover},
+  note={Open software from https://github.com/phurwicz/hover},
+  author={
+    Pavel Hurwicz and
+    Haochuan Wei},
+  year={2021},
+}
+```

docs/snippets/markdown/readme/6-remarks.zh.md

@@ -0,0 +1,28 @@
+## :bell: 其它说明
+
+### 鸣谢和推荐
+
+-   我们推荐 [`Bokeh`](https://bokeh.org) 可视化框架, `hover`正是基于它的图表同步和回调函数来实现非常重要的功能.
+-   感谢 [Philip Vollet](https://de.linkedin.com/in/philipvollet) 在`hover`的迭代早期 无偿地帮助在开源社区内推广.
+
+### 提供贡献
+
+-   我们欢迎任何反馈, **特别是使用中的痛点!**
+-   `./requirements-dev.txt` 列出了开发者所需的依赖.
+-   我们建议在提交PR前启用[.pre-commit-config.yaml](https://github.com/phurwicz/hover/blob/main/.pre-commit-config.yaml)中列出的pre-commit hook.
+
+### 引用
+
+如果`hover`对您的工作有帮助, 请[告诉我们](https://github.com/phurwicz/hover/discussions)或引用 :hugs:
+
+```tex
+@misc{hover,
+  title={{hover}: label data at scale},
+  url={https://github.com/phurwicz/hover},
+  note={Open software from https://github.com/phurwicz/hover},
+  author={
+    Pavel Hurwicz and
+    Haochuan Wei},
+  year={2021},
+}
+```