From 89c8aeaca5a7bf70cc1cfd0a9aec24102fe0dc3a Mon Sep 17 00:00:00 2001
From: Ron Stone <ronald.stone@windriver.com>
Date: Fri, 24 Sep 2021 13:13:40 -0400
Subject: [PATCH] Unique rST file names

As discussed, a simple script to create stubs with unique names and labels.
Prefix name of index files with "index-" to distinguish them from 'regular'
files.
Added missing "::" to templated rubrics.
Remove unneeded echo.

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: I8f7dd8f4a57655032de6913d4570f5ca5c2b9338
Signed-off-by: Ron Stone <ronald.stone@windriver.com>
---
 new-topic.sh                  | 136 ++++++++++++++++++++++++++++++++++
 templates/topic-templates.txt |  78 +++++++++++++++++++
 tox.ini                       |   9 +++
 3 files changed, 223 insertions(+)
 create mode 100644 new-topic.sh
 create mode 100644 templates/topic-templates.txt

diff --git a/new-topic.sh b/new-topic.sh
new file mode 100644
index 000000000..0a0a9b5c1
--- /dev/null
+++ b/new-topic.sh
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+
+if ! hash uuidgen 2>/dev/null; then
+  echo >&2 "... uuidgen dependency not met. Please install."
+  exit 1
+fi
+
+ask_name () {
+
+   echo -e "`cat <<EOF
+
+   You are about to create a new reStructuredText file in
+
+   ${WD}
+
+   If this is not what you want, press CTL-C to quit and change to the directory
+   you want to create the file in.
+
+   Enter a title for the new topic. The file name and topic label used for
+   linking will be based on this value.
+
+
+EOF`"
+
+
+    while read -e -p 'Topic title: ' title ; do
+      if [[ -z $title ]]; then
+         continue
+      else
+         break
+      fi
+    done
+
+}
+
+
+
+ask_type () {
+
+  echo -e "`cat <<EOF
+
+  Thanks. Now choose a topic type. Enter one of the following characters:
+
+    t) A task topic. Will contain the outline of a procedure.
+    i) An index.
+    r) A reference topic. Will contain a minimal list-table definition.
+    g) A minimal generic topic.
+
+EOF`"
+
+    while read -p 'Topic type: ' -n1 input; do
+
+       case $input in
+
+           t|i|r|g)
+              break
+             ;;
+
+           *)
+             echo -e "Enter a valid value"
+             continue
+             ;;
+
+        esac
+
+    done
+
+}
+
+write_stub () {
+
+   echo "$1" > "${WD}/${filename}.rst"
+   if [[ -f ${WD}/${filename}.rst ]]; then
+     echo -e "\nCreated ${WD}/${filename}.rst"
+     exit 0
+   else
+     exit 1
+   fi
+
+}
+
+
+WD=$1
+
+myuuid=$(uuidgen)
+
+# Keep as fallback?
+# myuuid="$(od -x /dev/urandom | head -1 | awk '{OFS="-"; print $2$3,$4,$5,$6,$7$8$9}')"
+
+
+myuuid="${myuuid:24:35}"
+
+ask_name
+
+strike=$(for ((i=1; i<=${#title}; i++)); do
+  printf '=%.0s' "$i"
+done)
+
+
+ask_type
+
+filename="${title//[^[:alnum:]]/-}"
+filename=$(echo $filename | tr -s -)
+filename=${filename,,}
+filename="${filename}-${myuuid}"
+[ $input == "i" ] && filename="index-${filename}"
+
+CONTEXT_DIR="${BASH_SOURCE%/*}"
+if [[ ! -d "$CONTEXT_DIR" ]]; then CONTEXT_DIR="$PWD"; fi
+. "$CONTEXT_DIR/templates/topic-templates.txt"
+
+case $input in
+
+   t)
+     write_stub "${task}"
+     ;;
+
+   i)
+     write_stub "${index}"
+     ;;
+
+   r)
+      write_stub "${reference}"
+      ;;
+
+   g)
+      write_stub "${topic}"
+      ;;
+
+   *)
+      echo -e "$input not valid"
+      ;;
+
+esac
+
+
diff --git a/templates/topic-templates.txt b/templates/topic-templates.txt
new file mode 100644
index 000000000..e97f97f42
--- /dev/null
+++ b/templates/topic-templates.txt
@@ -0,0 +1,78 @@
+echo "Loading topic types ..."
+
+# Add convenience templates for rst content here.
+
+# Task-oriented procedures
+task=".. _$filename:
+
+$strike
+$title
+$strike
+
+.. rubric:: |context|
+
+.. context here
+
+.. rubric:: |prereq|
+
+.. prerequisites here
+
+.. rubric:: |proc|
+
+#. Step 1
+
+#. Step 2
+
+.. rubric:: |result|
+
+.. procedure results here
+"
+# EOT
+
+
+# Index file names should be unique across all repos
+index=".. _$filename:
+
+$strike
+$title
+$strike
+
+.. Uncomment topic-a etc. below and replace with the names of your topics,
+   excluding the ".rst" extension
+
+.. toctree::
+   :maxdepth: 2
+
+..   topic-a
+..   topic-b
+"
+
+# Tabular data
+reference=".. _$filename:
+
+$strike
+$title
+$strike
+
+.. See https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
+
+.. list-table::
+
+   * - Column 1
+     - Column 2
+     - Column 3
+   * - Row 1, value 1
+     - Value 1
+     - Value 2
+"
+
+# Generic topic
+topic=".. _$filename:
+
+$strike
+$title
+$strike
+
+.. content here
+
+"
diff --git a/tox.ini b/tox.ini
index 1595a5a6d..6883a1845 100644
--- a/tox.ini
+++ b/tox.ini
@@ -38,3 +38,12 @@ commands =
 
 [testenv:venv]
 commands = {posargs}
+
+
+[testenv:newfile]
+passenv=PWD
+commands =
+       bash -c "echo Running in {env:PWD}"
+       bash new-topic.sh {env:PWD}
+whitelist_externals = new-topic.sh
+                      bash