From 8a90695ce2179e6ebfc4cd748ca6147452565556 Mon Sep 17 00:00:00 2001 From: Matthias Fischer Date: Wed, 24 Jan 2024 18:04:33 +0100 Subject: [PATCH 1/3] chore(docs):[#xxx] Helper script for building docs locally --- docs/build-docs-locally.sh | 108 +++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/build-docs-locally.sh diff --git a/docs/build-docs-locally.sh b/docs/build-docs-locally.sh new file mode 100644 index 0000000000..b0b578a0c2 --- /dev/null +++ b/docs/build-docs-locally.sh @@ -0,0 +1,108 @@ +################################################################################# +# Copyright (c) 2022,2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG) +# Copyright (c) 2021,2024 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Apache License, Version 2.0 which is available at +# https://www.apache.org/licenses/LICENSE-2.0. +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# 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 +# +################################################################################## + + +WD=$(pwd) +echo "$WD" + + +read -p "Do you want to build the API documentation? (y/n): " build_docs +if [ "$build_docs" == "y" ] || [ "$build_docs" == "Y" ]; then + 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 "Skipping API documentation." +fi + + +echo "Building documentation with Maven..." +mvn -f docs/pom.xml clean generate-resources --batch-mode + +echo "Reducing docs..." +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 "Downloading PlantUML..." +wget -O plantuml.jar https://sourceforge.net/projects/plantuml/files/plantuml.jar/download +cp plantuml.jar docs/src/diagram-replacer/ + +echo "Extracting PNG images from documentation..." +pwd +cd docs/src/diagram-replacer/ || exit +pwd +node extract.js + +echo "Replacing PlantUML code in docs with PNG images..." +node replace.js +cd "$WD" || exit +pwd + +echo "Converting adminguide to Markdown..." +npx downdoc -o docs/target/generated-docs/adminguide.md docs/src/diagram-replacer/generated-adocs/adminguide.adoc +echo "Converting arc42 documentation to Markdown..." +npx downdoc -o docs/target/generated-docs/arc42.md docs/src/diagram-replacer/generated-adocs/arc42.adoc + +echo "Post-processing markdown files" +cd docs/src/post-processing/ || exit +pwd + +node fix_headers.js +node fix_no_emphasis.js +node fix_https_links.js +node fix_relative_links.js + +cd "$WD" || exit +pwd + +echo "Markdown linting..." +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 "Moving assets to target directory..." +DOCTARGET="docs/target/generated-docs/assets/" +mv docs/src/diagram-replacer/assets/ $DOCTARGET + +echo "Finished generating documentation: $DOCTARGET" \ No newline at end of file From 5fa6082b847d5c0ca86e28efab81cd97f6ba9929 Mon Sep 17 00:00:00 2001 From: Matthias Fischer Date: Wed, 24 Jan 2024 18:43:49 +0100 Subject: [PATCH 2/3] 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 From 1c4848590fd9f4d30bfd201c9908f7609ca0cbbe Mon Sep 17 00:00:00 2001 From: Matthias Fischer Date: Wed, 24 Jan 2024 18:46:09 +0100 Subject: [PATCH 3/3] chore(docs):[#xxx] Update CHANGELOG.md --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 57c9c48532..ba2efcc120 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Changed +### Added +- Added helper script for building documentation locally. +### Changed - Updated license header to "Copyright (c) 2021,2024 Contributors to the Eclipse Foundation" - Changed lookupGlobalAssetIds to lookupShellsByBPN, which provides full object.