[ATfL] Add package documentation (#254)

It's a cherry-pick from the arm-software branch.

This patch adds the ATfL package documentation which should land into:

1. Our on-line page(s)

2. Our release .deb packages

3. Our release .rpm packages

The markdown documents introduced by this patch have landed into the
arm-software/linux/docs directory. This follows the same guidance that
has been already agreed for the ATfE product (see [1]).

Additionally, an index.md file has been created which follows the
convention already observed in the LLVM's documentation directories
(e.g., [2]).

The files from the arm-software/linux/docs directory are being copied
into the arm/docs directory of the tarball and this is happening in the
build.sh script also modified by this patch. Whatever lands into that
directory, should act as a basis for further rendering of the on-line
page(s) and the PDF document(s) in our CI pipelines.

[1]

https://github.com/arm/arm-toolchain/blob/arm-software/arm-software/docs/README.md

[2]

https://github.com/arm/arm-toolchain/blob/arm-software/flang/docs/index.md

Author: pawosm-arm

arm-software/docs/README.md

@@ -6,4 +6,5 @@ Toolchain for Embedded and Arm Toolchain for Linux.
 Documentation that is specific to a toolchain should be placed in the
 toolchain specific subdirectory. For example documentation for Arm
 Toolchain for Embedded should go into the `arm-software/embedded/docs`
-directory.
+directory while documentation for Arm Toolchain for Linux should go
+into the `arm-software/linux/docs` directory.

arm-software/linux/build.sh

@@ -16,6 +16,7 @@ MKMODULEDIRS_PATH=${MKMODULEDIRS_PATH:-"${BASE_DIR}/mkmoduledirs.sh.var"}
 SOURCES_DIR=${SOURCES_DIR:-"$(git -C "${BASE_DIR}" rev-parse --show-toplevel)"}
 LIBRARIES_DIR=${LIBRARIES_DIR:-"${BASE_DIR}/lib"}
 PATCHES_DIR=${PATCHES_DIR:-"${BASE_DIR}/patches"}
+DOCS_DIR=${DOCS_DIR:-"${BASE_DIR}/docs"}
 BUILD_DIR=${BUILD_DIR:-"${BASE_DIR}/build"}
 ATFL_DIR=${ATFL_DIR:-"${BUILD_DIR}/atfl"}
 LOGS_DIR=${LOGS_DIR:-"${BASE_DIR}/logs"}
@@ -186,6 +187,8 @@ Environment Variables:
                         (default: $LIBRARIES_DIR)
     PATCHES_DIR         The optional directory where all patches will be stored
                         (default: $PATCHES_DIR)
+    DOCS_DIR            The directory where ATfL documents will be stored
+                        (default: $DOCS_DIR)
     BUILD_DIR           The directory where all build output will be stored
                         (default: $BUILD_DIR)
     LOGS_DIR            The directory where all build logs will be stored
@@ -386,6 +389,8 @@ package() {
     cp "${SBOM_FILE_PATH}" "${ATFL_DIR}/ATfL-SBOM.spdx.json"
     mkdir -p "${ATFL_DIR}/arm"
     cp "${MKMODULEDIRS_PATH}" "${ATFL_DIR}/arm/mkmoduledirs.sh"
+    mkdir -p "${ATFL_DIR}/arm/docs"
+    cp "${DOCS_DIR}"/*.md "${ATFL_DIR}/arm/docs"
     sed -i "s/%ATFL_VERSION%/${ATFL_VERSION}/g" "${ATFL_DIR}/arm/mkmoduledirs.sh"
     sed -i "s/%ATFL_BUILD%/${BUILD_NUMBER:-"unknown"}/g" "${ATFL_DIR}/arm/mkmoduledirs.sh"
     sed -i "s/%ATFL_INSTALL_PREFIX%/\$\(dirname \$\(dirname \`realpath \$BASH_SOURCE\`\)\)/g" "${ATFL_DIR}/arm/mkmoduledirs.sh"
@@ -498,6 +503,12 @@ then
   exit 1
 fi
 
+if ! [[ -e "${DOCS_DIR}" ]]
+then
+  echo "The documentation directory is configured incorrectly or does not exist."
+  exit 1
+fi
+
 if ! [[ -e "${SOURCES_DIR}" ]]
 then
   echo "The sources directory is configured incorrectly or does not exist."

arm-software/linux/build.sh-HOWTO.md

@@ -147,6 +147,8 @@ The `build.sh` script reads the following environment variables:
   (default: `arm-software/linux/lib`)
 - `PATCHES_DIR` - The **optional** directory where all patches will be stored
   (default: `arm-software/linux/patches`)
+- `DOCS_DIR` - The directory where ATfL documents will be stored
+  (default: `arm-software/linux/docs`)
 - `BUILD_DIR` - The directory where all build will be happening
   (default: `arm-software/linux/build`)
 - `LOGS_DIR` - The directory where all build logs will be stored