Update upstream source from tag 'samconf-0.58.3'

Update to upstream version '0.58.3'
with Debian dir f28ec5d1e6ffa987985cfd9cc51108cdaa7ccac6

ci/Dockerfile

@@ -78,6 +78,7 @@ RUN python -m venv /home/$USER/.venv \
   && python -m pip install \
      beautifulsoup4==4.12.2  \
      clang==16.0.1.1 \
+     myst-parser==2.0.0 \
      sphinx==7.2.6 \
      sphinx-c-autodoc==1.3.0 \
      sphinx-copybutton==0.5.2 \

ci/build_doc.sh

@@ -1,14 +1,43 @@
 #!/bin/bash -eu
-
 CMD_PATH="$(realpath "$(dirname "$0")")"
 BASE_DIR="$(realpath "$CMD_PATH/..")"
 
+function printHelp() {
+    echo "Usage: $0 [options]"
+    echo "Options:"
+    echo -e "\t -c\t\tclean output directory and generated files before building"
+    echo -e "\t -h\t\tprint this help and exit"
+}
+
+PARAM=""
+OPTION_CLEAN=0
+for element in $@; do
+    case $element in
+        --clean|-c)
+            OPTION_CLEAN=1 ;;
+        --help|-h)
+            printHelp
+			exit 0 ;;
+        -*)
+            echo "error: unknown option: ${element}"
+            printHelp
+            exit 1 ;;
+        *)  PARAM="$PARAM $element" ;;
+    esac
+done
+
+set -- $PARAM
+BUILD_TYPE="${1:-Release}"
+BUILD_DIR="$BASE_DIR/build/$BUILD_TYPE"
+DIST_DIR="$BUILD_DIR/dist"
+
 MD_DOCUMENTAION_DIR="${BASE_DIR}/documentation"
 SAMCONF_SOURCE_SOURCE_DIR="${BASE_DIR}/src"
 
-SPHINX_SOURCE_DIR="${BASE_DIR}/doc/source"
-SPHINX_BUILD_DIR="${BASE_DIR}/build/doc"
-SPHINX_GENERATED_SOURCE_DIR="${BASE_DIR}/doc/source/generated"
+SPHINX_SOURCE_DIR=${BASE_DIR}
+SPHINX_BUILD_DIR=${BUILD_DIR}/doc
+SPHINX_GENERATED_SOURCE_DIR=${SPHINX_BUILD_DIR}/source_generated
+SPHINX_HTML_OUTPUT_DIR=${SPHINX_BUILD_DIR}/html
 
 . "${SPHINX_VENV-${BASE_DIR}/.venv/}/bin/activate"
 
@@ -19,41 +48,33 @@ function createApiDocu() {
     sphinx-c-apidoc --force \
 	    -o "${SPHINX_GENERATED_SOURCE_DIR}/api/" \
 	    --tocfile index \
-	    "${SAMCONF_SOURCE_SOURCE_DIR}/samconf/public"
+	    "${SAMCONF_SOURCE_SOURCE_DIR}/samconf/"
 }
 
 function createDeveloperDocu() {
-    cp -r "${MD_DOCUMENTAION_DIR}/images" "${SPHINX_GENERATED_SOURCE_DIR}/developer/"
-    pandoc --from gfm --to rst \
-	-o "${SPHINX_GENERATED_SOURCE_DIR}/developer/DeveloperManual.rst" \
-	"${MD_DOCUMENTAION_DIR}/developer.md"
-    pandoc --from gfm --to rst \
-	-o "${SPHINX_GENERATED_SOURCE_DIR}/developer/documentation.rst" \
-	"${MD_DOCUMENTAION_DIR}/documentation.md"
-
     sphinx-c-apidoc --force \
 	    -o "${SPHINX_GENERATED_SOURCE_DIR}/developer/api/" \
 	    --tocfile index \
-	    "${BASE_DIR}/test/utest/utils/public"
-
-    echo -e "
-Developer documentation
-==========================
-
-.. toctree::
-  :maxdepth: 1
-  :caption: Contents:
-
-  DeveloperManual
-  documentation
-  API<api/index>
-
-" > "${SPHINX_GENERATED_SOURCE_DIR}/developer/index.rst"
+	    "${BASE_DIR}/test/utest/utils/"
 }
 
 createApiDocu
 createDeveloperDocu
 
 export PATH="${PATH}:${BASE_DIR}/build/Release/dist/usr/local/bin"
 export LD_LIBRARY_PATH="${LD_LIBRARY_PATH-"./"}:${BASE_DIR}/build/Release/dist/usr/local/lib"
-sphinx-build -b html "${SPHINX_SOURCE_DIR}" "${SPHINX_BUILD_DIR}"
+
+sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_HTML_OUTPUT_DIR} 2> ${SPHINX_BUILD_DIR}/html_doc_error.log
+if [ $? -ne 0 ]; then
+    echo "Build failed, for details see ${SPHINX_BUILD_DIR}/html_doc_error.log"
+    exit 1
+fi
+
+WARNINGS=$(grep -e ": WARNING:" -e ": ERROR:" ${SPHINX_BUILD_DIR}/html_doc_error.log | wc -l)
+if [ ${WARNINGS} -ne 0 ]; then
+    echo ""
+    echo "Build warnings ${WARNINGS}"
+    echo ""
+    cat ${SPHINX_BUILD_DIR}/html_doc_error.log
+    exit 1
+fi

ci/index.rst

@@ -100,6 +100,7 @@ and call `install_deps.py` like :
    SOURCES_URI=https://${GIT_USER_TOKEN}@github.com/Elektrobit/
 
 These dependencies get installed into `build/deps/` and if provided with an URL the sources can be found in `build/deps/src`.
+To use binaries installed from dependencies add `build/deps/bin` to the `PATH` environment variable.
 
 `ci/build.sh`
 -------------

cmake/index.rst

@@ -4,3 +4,15 @@ CMake options
 .. program-output:: cmake -LH 2>/dev/null | sed '0,/^-- Cache values$/d'
    :shell:
 
+
+Usage of find_package
+=====================
+
+* Always specify a version. `find_package(dependecy X.Y.Z REQUIRED)`
+* Specify the version used for development
+
+
+* The version doesn't guarantee that in the future the build still works with this version.
+* The version does not necessarily say the previous versions will not work.
+* The version is just an indicator for later issue or bug tracking, to say: "It was developed with this version and it worked".
+* Usually we always build against the latest available version of our dependencies, so we only can guarantee that the latest upstream version will work.

cmake/project.cmake

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-set(SAMCONF_VERSION 0.57.1)
+set(SAMCONF_VERSION 0.58.3)
 
 # Attention: Aside from the version, as many things as possible in this file
 #   should be put into functions, as this solves potential issues with commands

doc/source/conf.py → conf.py

@@ -14,6 +14,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    'myst_parser',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinxcontrib.programoutput',
@@ -29,22 +30,23 @@
     'sphinx_c_autodoc.viewcode',
 ]
 
-templates_path = ['_templates']
-exclude_patterns = []
-
+templates_path = ['doc/_templates']
+exclude_patterns = ['build/deps/**', 'build/*/cmake/_deps/*', 'README.md', '.venv', 'debian.native/devdoc-index.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 language = 'en'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'alabaster'
-html_static_path = ['_static']
+html_static_path = ['doc/source/_static']
 
 # c-autodoc
 c_autodoc_roots = [
-    '../../src/samconf/private',
-    '../../src/samconf/public',
-    '../../test/utest/utils/public',
-    '../../test/utest/utils/private',
+    'src/samconf',
+    'test/utest/utils',
 ]
 set_type_checking_flag = True

documentation/adr/ADR_template.md

@@ -0,0 +1,81 @@
+# Design Decisions - <headline>
+
+## Problem
+
+<describe the problem>
+
+## Influencing factors
+
+The following constraints have to be taken into account for a suitable solution:
+* <first>
+* <second>
+
+
+
+## Assumptions
+
+The following assumptions have been made in the decision process:
+* <first>
+* <second>
+
+
+
+## Considered Alternatives
+
+### 1) <alt 1>
+
+Description of this alternative.
+
+*pros*
+* <first>
+** But: <if applicable react to the above with a but...>
+* <second>
+** But:
+
+*cons*
+* <first>
+** But: <if applicable react to the above with a but...>
+* <second>
+** But:
+
+### 2) <alt 2>
+
+Description of this alternative.
+
+*pros*
+* <first>
+** But: <if applicable react to the above with a but...>
+* <second>
+** But:
+
+*cons*
+* <first>
+** But: <if applicable react to the above with a but...>
+* <second>
+** But:
+
+### 3) <alt 3>
+
+Description of this alternative.
+
+*pros*
+* <first>
+** But: <if applicable react to the above with a but...>
+* <second>
+** But:
+
+*cons*
+* <first>
+** But: <if applicable react to the above with a but...>
+* <second>
+** But:
+
+## Decision
+
+Alternative 42 is taken.
+
+### Rationale
+
+### Open Points
+
+if something was left open after this decision

documentation/adr/index.rst

@@ -0,0 +1,30 @@
+Architecture Design Records
+===========================
+
+During the development of samconf, decisions have to be made. This chapter
+provides a place to collect new ideas and discuss them until we are able to
+agree on a final decision for a topic.
+
+
+An *Architecture Design Record* (**ADR**) should follow roughly the pattern
+
+* Problem Description
+* Influencing factors
+* Assumptions
+* Considered Alternatives
+* Decision
+  * Rational
+  * Open Points
+
+There is an ADR-Template :doc:`ADR_template` which can be started with.
+
+
+List of ADRs
+------------
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   ./ADR_template
+   ./source_verification.md