From 5fa6082b847d5c0ca86e28efab81cd97f6ba9929 Mon Sep 17 00:00:00 2001
From: Matthias Fischer <matthias.fischer@doubleslash.de>
Date: Wed, 24 Jan 2024 18:43:49 +0100
Subject: [PATCH] chore(docs):[#xxx] Improve helper script output and adjust
 .gitignore

---
 .gitignore                 |  8 ++++
 docs/build-docs-locally.sh | 88 +++++++++++++++++++++++++++-----------
 2 files changed, 70 insertions(+), 26 deletions(-)

diff --git a/.gitignore b/.gitignore
index aa50006305..b8702c8954 100644
--- a/.gitignore
+++ b/.gitignore
@@ -62,3 +62,11 @@ local/testing/api-tests/__pycache__/
 
 ### Cucumber ###
 /irs-cucumber-tests/report.json
+
+### Local documentation build ###
+node_modules
+docs/src/diagram-replacer/generated-adocs
+docs/src/diagram-replacer/package-lock.json
+docs/src/diagram-replacer/package.json
+docs/src/diagram-replacer/plantuml.jar
+
diff --git a/docs/build-docs-locally.sh b/docs/build-docs-locally.sh
index b0b578a0c2..a0a9433586 100644
--- a/docs/build-docs-locally.sh
+++ b/docs/build-docs-locally.sh
@@ -18,74 +18,101 @@
 # SPDX-License-Identifier: Apache-2.0
 ##################################################################################
 
-
-##################################################################################
-# Helper script for generating the documentation locally in WSL.
-# The commands are copied from .github/workflows/publish-documentation.yaml.
-#
-# Prerequisistes:
-#
-#    1) Install Java 17 (OpenJDK)
-#         sudo apt install openjdk-17-jdk openjdk-17-jre
-#    2) Install NodeJS
-#         sudo apt install nodejs
-#    3) Install asciidoctor-reducer
-#         sudo apt install ruby
-#         sudo gem install asciidoctor-reducer
-#    4) Install markdown lint cli
-#         npm install markdownlint-cli2
-#
-# Please run this script from repository root:
-#
-#    ./docs/build-docs-locally.sh
-#
-##################################################################################
+echo
+echo "##################################################################################"
+echo "# Helper script for generating the documentation locally in WSL."
+echo "# The commands are copied from .github/workflows/publish-documentation.yaml."
+echo "#"
+echo "# Prerequisistes:"
+echo "#"
+echo "#    1) Install Java 17 (OpenJDK)"
+echo "#         sudo apt install openjdk-17-jdk openjdk-17-jre"
+echo "#    2) Install NodeJS"
+echo "#         sudo apt install nodejs"
+echo "#    3) Install asciidoctor-reducer"
+echo "#         sudo apt install ruby"
+echo "#         sudo gem install asciidoctor-reducer"
+echo "#    4) Install markdown lint cli"
+echo "#         npm install markdownlint-cli2"
+echo "#"
+echo "# Please run this script from repository root:"
+echo "#"
+echo "#    ./docs/build-docs-locally.sh"
+echo "#"
+echo "##################################################################################"
+
+echo
+read -p "Continue? (y/n): " startbuild
+
+if [[ ! "$startbuild" =~ ^[Yy]$ ]]; then
+    echo
+    exit 0
+fi
 
 
 WD=$(pwd)
 echo "$WD"
 
-
+echo
 read -p "Do you want to build the API documentation? (y/n): " build_docs
+
 if [ "$build_docs" == "y" ] || [ "$build_docs" == "Y" ]; then
+    echo
     echo "Building API documentation with Maven..."
     mvn clean package -pl irs-common,irs-models,irs-policy-store,irs-testing,irs-edc-client,irs-registry-client,irs-api -DskipTests --batch-mode
     cp irs-api/target/generated-sources/openapi/index.html docs/src/docs/api-specification/index.html
 else
+    echo
     echo "Skipping API documentation."
 fi
 
-
+echo
 echo "Building documentation with Maven..."
+echo
 mvn -f docs/pom.xml clean generate-resources --batch-mode
 
+echo
 echo "Reducing docs..."
+echo
 echo "$LANG"
 locale
 asciidoctor-reducer -o docs/target/adminguide.adoc docs/src/docs/administration/administration-guide.adoc
 asciidoctor-reducer -o docs/target/arc42.adoc docs/src/docs/arc42/full.adoc
 
+echo
 echo "Downloading PlantUML..."
+echo
 wget -O plantuml.jar https://sourceforge.net/projects/plantuml/files/plantuml.jar/download
-cp plantuml.jar docs/src/diagram-replacer/
+mv plantuml.jar docs/src/diagram-replacer/
 
+echo
 echo "Extracting PNG images from documentation..."
+echo
 pwd
 cd docs/src/diagram-replacer/ || exit
 pwd
 node extract.js
 
+echo
 echo "Replacing PlantUML code in docs with PNG images..."
+echo
 node replace.js
 cd "$WD" || exit
 pwd
 
+echo
 echo "Converting adminguide to Markdown..."
+echo
 npx downdoc -o docs/target/generated-docs/adminguide.md docs/src/diagram-replacer/generated-adocs/adminguide.adoc
+
+echo
 echo "Converting arc42 documentation to Markdown..."
+echo
 npx downdoc -o docs/target/generated-docs/arc42.md docs/src/diagram-replacer/generated-adocs/arc42.adoc
 
+echo
 echo "Post-processing markdown files"
+echo
 cd docs/src/post-processing/ || exit
 pwd
 
@@ -97,12 +124,21 @@ node fix_relative_links.js
 cd "$WD" || exit
 pwd
 
+echo
 echo "Markdown linting..."
+echo
 npx markdownlint-cli2 --config docs/.markdownlint.yaml docs/target/generated-docs/adminguide.md
 npx markdownlint-cli2 --config docs/.markdownlint.yaml docs/target/generated-docs/arc42.md
 
+echo
 echo "Moving assets to target directory..."
+echo
 DOCTARGET="docs/target/generated-docs/assets/"
 mv docs/src/diagram-replacer/assets/ $DOCTARGET
 
-echo "Finished generating documentation: $DOCTARGET"
\ No newline at end of file
+echo
+echo "----------------------------------------------"
+echo "Finished generating documentation:"
+echo   $DOCTARGET
+echo "----------------------------------------------"
+echo
\ No newline at end of file