From 3b02e2ebe2b19a563499f238377b0632a2aded4c Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Tue, 30 Aug 2022 11:22:56 -0700
Subject: [PATCH] doc: add a doc helper script

changed-docs.sh (and the accompanying awk script) shows docs changed
between a previous release branch and the current master branch, in a format that
can be used for the releae notes (a list of :ref: items).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
---
 doc/scripts/changed-docs.awk | 40 ++++++++++++++++++++++++++++++++++++
 doc/scripts/changed-docs.sh  | 27 ++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 doc/scripts/changed-docs.awk
 create mode 100755 doc/scripts/changed-docs.sh

diff --git a/doc/scripts/changed-docs.awk b/doc/scripts/changed-docs.awk
new file mode 100644
index 000000000..23cab2518
--- /dev/null
+++ b/doc/scripts/changed-docs.awk
@@ -0,0 +1,40 @@
+# parse the git diff --stat output and created a reST list of
+# (significantly) changed files
+#
+# doc/develop.rst                                    |   2 +
+# doc/developer-guides/contribute_guidelines.rst     | 116 +++-
+# doc/developer-guides/hld/hld-devicemodel.rst       |   8 +-
+# doc/developer-guides/hld/hld-hypervisor.rst        |   1 +
+# doc/developer-guides/hld/hv-rdt.rst                | 126 ++--
+# doc/developer-guides/hld/ivshmem-hld.rst           |  70 ++
+# doc/developer-guides/hld/mmio-dev-passthrough.rst  |  40 ++
+# doc/developer-guides/hld/virtio-net.rst            |  42 +-
+# doc/developer-guides/hld/vuart-virt-hld.rst        |   2 +-
+# doc/getting-started/building-from-source.rst       |  39 +-
+
+
+function getLabel(filename)
+{
+   label="Label not found in " filename
+   while ((getline line < filename) > 0) {
+      # looking for first occurance of  .. _label name here:
+      if (match(line, /^\.\. _([^:]+):/, a) !=0) {
+         label=a[1]
+         break
+      }
+   }
+   close(filename)
+   return label
+}
+
+BEGIN {
+    if (changes < 1) {changes=10}
+    print "Showing docs in master branch with " changes " or more changes."
+}
+
+# print label for files with more than specified changed lines
+$3 >= changes {
+   lable=getLabel($1)
+   if (label !~ /^Label not/ ) { print "* :ref:`" label "`" }
+   else { print "* " substr($1,5) " was deleted." }
+}
diff --git a/doc/scripts/changed-docs.sh b/doc/scripts/changed-docs.sh
new file mode 100755
index 000000000..000b73d5c
--- /dev/null
+++ b/doc/scripts/changed-docs.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+# Create a reST :ref: list of changed documents for the release notes
+# comparing the specified tag with master branch
+#
+#
+
+if [ -z $1 ]; then
+   echo
+   echo Create a reST :ref: list of change documents for the release notes
+   echo comparing the specified tag with the master branch
+   echo
+   echo Usage:
+   echo \ \ changed-docs.sh upstream/release_3.0 [changed amount]
+   echo
+   echo \ \ where the optional [changed amount] \(default 10\) is the number
+   echo \ \ of lines added/modified/deleted before showing up in this report.
+   echo
+elif [ "$(basename $(pwd))" != "acrn-hypervisor" ]; then
+   echo
+   echo Script must be run in the acrn-hypervisor directory and not $(basename $(pwd))
+else
+    dir=`dirname $0`
+
+    git diff --stat `git rev-parse $1` `git rev-parse master` | \
+       grep \.rst | \
+       awk -v changes=$2 -f $dir/changed-docs.awk
+fi