From f0583cd4ac5953b3cbc4f5531cef13b5329c5e85 Mon Sep 17 00:00:00 2001
From: Andrei Pashkin <andrew.pashkin@gmx.co.uk>
Date: Sun, 9 Feb 2025 02:26:18 +0100
Subject: [PATCH] refactor(docs): make README.md re-use the usage example

---
 .github/workflows/build.yml |  7 +++-
 README.md.tpl               | 70 +++++++++++++++++++++++++++++++++++++
 Taskfile.yml                |  3 ++
 3 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 README.md.tpl

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index a36f4ab..33a0c15 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -17,8 +17,11 @@ jobs:
         version: 3.x
         repo-token: ${{ secrets.GITHUB_TOKEN }}
     - uses: pre-commit/action@v3.0.1
+    - uses: pkgxdev/setup@v3
     - name: Set up Rust toolchain
       run: rustup update stable && rustup default stable
+    - name: Set up additional tools
+      run: pkgm install gomplate.ca
     - name: Lint
       run: task lint
     - name: Build
@@ -26,4 +29,6 @@ jobs:
     - name: Run tests
       run: task test
     - name: Build docs
-      run: cargo doc --verbose
+      run: |
+        task render
+        cargo doc --verbose
diff --git a/README.md.tpl b/README.md.tpl
new file mode 100644
index 0000000..25f9df1
--- /dev/null
+++ b/README.md.tpl
@@ -0,0 +1,70 @@
+![Build](https://github.com/AndreiPashkin/compose-idents/actions/workflows/build.yml/badge.svg)
+[![Crates.io Version](https://img.shields.io/crates/v/compose-idents)](https://crates.io/crates/compose-idents)
+[![docs.rs](https://img.shields.io/docsrs/compose-idents)](https://docs.rs/compose-idents)
+
+# compose-idents
+
+A procedural macro that allows to construct identifiers from one or more arbitrary parts.
+
+## Motivation
+
+Rust's declarative macros do not allow generating new identifiers, because they are designed to operate on
+the syntactic level (as opposed to the lexical level) using simple pattern matching.
+
+For example the following code won't work:
+```rust,compile_fail
+{{ file.Read "examples/usage.rs" }}
+```
+
+Here is a more practical example for how to auto-generate names for macro-generated tests for different data types:
+```rust
+use std::ops::Add;
+use compose_idents::compose_idents;
+
+fn add<T: Add<Output = T>>(x: T, y: T) -> T {
+  x + y
+}
+
+macro_rules! generate_add_tests {
+    ($($type:ty),*) => {
+      $(
+        compose_idents!(test_fn = [test_add_, $type]; {
+          fn test_fn() {
+            let actual = add(2 as $type, 2 as $type);
+            let expected = (2 + 2) as $type;
+
+            assert_eq!(actual, expected);
+          }
+        });
+      )*
+    };
+}
+
+generate_add_tests!(u8, u32, u64);
+
+test_add_u8();
+test_add_u32();
+test_add_u64();
+```
+
+For more usage examples look into `examples/` and `tests/` directories of the repository.
+
+## Alternatives
+
+There some other tools and projects dedicated to identifier manipulation:
+
+- A macro from Nightly Rust that allows to concatenate identifiers. It is limited in functionality and nowhere near
+  to be stabilized:
+  <https://doc.rust-lang.org/std/macro.concat_idents.html>
+- A very similar macro that doesn't support multiple aliases and is not maintained:
+  <https://github.com/DzenanJupic/concat-idents>
+- A macro that allows to define and refer to unique temporary variables:
+  <https://crates.io/crates/templest>
+
+## Development
+
+The following standards are followed to maintain the project:
+- <https://www.conventionalcommits.org/en/v1.0.0/>
+- <https://semver.org/>
+- <https://keepachangelog.com/en/1.1.0/>
+- <https://adr.github.io/madr/>
diff --git a/Taskfile.yml b/Taskfile.yml
index b321058..ea401a9 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -11,3 +11,6 @@ tasks:
   lint:
     cmds:
       - pre-commit run --all
+  render:
+    cmds:
+      - gomplate -f README.md.tpl -o README.md