doc: add index to README.md

Signed-off-by: Rodolfo Mói de Oliveira <rodmoi.oliveira@gmail.com>
rodmoioliveira · Oct 22, 2024 · 6656c08 · 6656c08
1 parent ffe368d
commit 6656c08
Show file tree

Hide file tree

Showing 3 changed files with 96 additions and 16 deletions.
diff --git a/Makefile b/Makefile
@@ -6,10 +6,10 @@ help: ## Display this help screen
 		{printf "%-20s %s\n", $$1, $$2}' | \
 		sort
 
-readme: ## Write README.md
+doc-readme: ## Write README.md
 	@./dev/readme.sh
 
-changelog: ## Write CHANGELOG.mode
+doc-changelog: ## Write CHANGELOG.mode
 	@git cliff -o CHANGELOG.md
 
 typos: ## Check typos
@@ -32,10 +32,6 @@ rs-cargo-deps: ## Install cargo dependencies
 	@cargo install cargo-audit --features=fix
 	@cargo install cargo-udeps --locked
 	@cargo install cargo-watch
-	@cargo install eza
-	@cargo install bat
-	@cargo install ripgrep
-	@cargo install sd
 	@cargo install typos-cli
 	@rustup component add clippy
 
@@ -97,8 +93,8 @@ bash-lint: ## Check lint bash code
 .PHONY: bash-check
 .PHONY: bash-fmt
 .PHONY: bash-lint
-.PHONY: changelog
-.PHONY: readme
+.PHONY: doc-changelog
+.PHONY: doc-readme
 .PHONY: rs-audit
 .PHONY: rs-audit-fix
 .PHONY: rs-build

diff --git a/README.md b/README.md
@@ -5,12 +5,23 @@ collatz is a CLI for printing the [hailstone sequence](https://en.wikipedia.org/
 [![Build status](https://github.com/rodmoioliveira/collatz/workflows/ci/badge.svg)](https://github.com/rodmoioliveira/collatz/actions)
 [![GitHub Release](https://img.shields.io/github/v/release/rodmoioliveira/collatz)](https://github.com/rodmoioliveira/collatz/releases)
 
-## Installation
+# index
+
+  - [Installation](#installation)
+  - [Building](#building)
+  - [Usage](#usage)
+  - [Make Recipes](#make-recipes)
+
+# Installation
+
+[back^](#index)
 
 Archives of [precompiled binaries](https://github.com/rodmoioliveira/collatz/releases)
 for `collatz` are available for Windows, macOS and Linux.
 
-## Building
+# Building
+
+[back^](#index)
 
 `collatz` is written in Rust, so you'll need to grab a [Rust installation](https://www.rust-lang.org/tools/install)
 in order to compile it. To build `collatz`, run:
@@ -21,7 +32,9 @@ cd collatz
 make install
 ```
 
-## Usage
+# Usage
+
+[back^](#index)
 
 ```
 collatz --help
@@ -41,3 +54,36 @@ Options:
   -V, --version
           Print version
 ```
+
+# Make Recipes
+
+[back^](#index)
+
+```
+bash-all             Run all bash tests
+bash-check           Check format bash code
+bash-fmt             Format bash code
+bash-lint            Check lint bash code
+doc-changelog        Write CHANGELOG.mode
+doc-readme           Write README.md
+help                 Display this help screen
+rs-audit             Audit Cargo.lock
+rs-audit-fix         Update Cargo.toml to fix vulnerable dependency requirement
+rs-build             Build binary
+rs-cargo-deps        Install cargo dependencies
+rs-check             Run check
+rs-dev               Run check in watch mode
+rs-doc               Open app documentation
+rs-fix               Fix rust code
+rs-fmt-fix           Format fix rust code
+rs-fmt               Format rust code
+rs-install           Install binary
+rs-lint-fix          Fix lint rust code
+rs-lint              Lint rust code
+rs-outdated          Display when dependencies are out of date
+rs-tests             Run tests
+rs-uninstall         Uninstall binary
+rs-update-cargo      Update dependencies
+typos                Check typos
+typos-fix            Fix typos
+```
diff --git a/dev/readme.sh b/dev/readme.sh
@@ -5,6 +5,33 @@ declare TRACE
 set -o errexit
 set -o nounset
 set -o pipefail
+shopt -s inherit_errexit
+
+index() {
+  paste -d "" \
+    <(
+      cat dev/readme.sh |
+        grep -E '^#{1,} [A-Z]' |
+        sed 's/^ {1,}//g' |
+        sed -E 's/(^#{1,}) (.+)/\1\[\2]/g' |
+        sed 's/#/  /g' |
+        sed -E 's/\[/- [/g'
+    ) \
+    <(
+      cat dev/readme.sh |
+        grep -E '^#{1,} [A-Z]' |
+        sed 's/#//g' |
+        sed -E 's/^ {1,}//g' |
+        sed -E 's/[?,]//g' |
+        sed 's/[A-Z]/\L&/g' |
+        sed 's/ /-/g' |
+        sed -E 's@(.+)@(#\1)@g'
+    )
+}
+
+backlink() {
+  sed -i -E '/^##? [A-Z]/a\\n\[back^\](#index)' README.md
+}
 
 readme() {
   cat <<EOF >README.md
@@ -15,12 +42,16 @@ collatz is a CLI for printing the [hailstone sequence](https://en.wikipedia.org/
 [![Build status](https://github.com/rodmoioliveira/collatz/workflows/ci/badge.svg)](https://github.com/rodmoioliveira/collatz/actions)
 [![GitHub Release](https://img.shields.io/github/v/release/rodmoioliveira/collatz)](https://github.com/rodmoioliveira/collatz/releases)
 
-## Installation
+# index
+
+$(index)
+
+# Installation
 
 Archives of [precompiled binaries](https://github.com/rodmoioliveira/collatz/releases)
 for \`collatz\` are available for Windows, macOS and Linux.
 
-## Building
+# Building
 
 \`collatz\` is written in Rust, so you'll need to grab a [Rust installation](https://www.rust-lang.org/tools/install)
 in order to compile it. To build \`collatz\`, run:
@@ -31,17 +62,24 @@ cd collatz
 make install
 \`\`\`
 
-## Usage
+# Usage
 
 \`\`\`
 cargo run -- --help
 
 $(cargo run -- --help)
 \`\`\`
+
+# Make Recipes
+
+\`\`\`
+$(make help)
+\`\`\`
 EOF
 
-  sd '(make\[1\]:.+\n)' '' README.md
-  sd 'cargo run --' 'collatz' README.md
+  sed -i -E '/^make\[[0-9]/d' README.md
+  sed -i -E 's/cargo run --/collatz/g' README.md
+  backlink
 }
 
 trap readme EXIT