feat: add creation of variant docs

backup
avengineers · Jan 4, 2024 · 5a21b92 · 5a21b92
1 parent 17d354e
commit 5a21b92
Show file tree

Hide file tree

Showing 22 changed files with 1,152 additions and 1,162 deletions.
diff --git a/Pipfile b/Pipfile
@@ -4,28 +4,35 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-conan = {version="==1.59.0"}
 cookiecutter = {version="==2.1.1"}
 gcovr = "*"
 hammocking = "*"
 kconfiglib = "*"
 
 [dev-packages]
+jinja2 = "*"
 pytest = "*"
+pytest-env = "*"
 pytest-cov = "*"
-pipenv = "*"
+testfixtures = "*"
+junitparser = "*"
+mashumaro = "*"
+loguru = "*"
+black = "*"
 m2r = "*"
 flake8 = "*"
 sphinx = "*"
 sphinx-rtd-theme = "*"
 sphinxcontrib-mermaid = "*"
 sphinx-needs = "*"
 sphinx-test-reports = "*"
-sphinxcontrib-plantuml = "*"
 doxysphinx = "*"
 sphinx-rtd-size = "*"
+sphinxcontrib-datatemplates = "*"
+sphinxcontrib-plantuml = "*"
 sphinx-copybutton = "*"
 sphinx-new-tab-link = "*"
+pipenv = "*"
 
 [requires]
 python_version = "3.11"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/cmake/common.cmake b/cmake/common.cmake
@@ -95,7 +95,7 @@ endmacro(_spl_get_google_test)
 macro(spl_create_component)
     file(RELATIVE_PATH component_path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_LIST_DIR})
     _spl_slash_to_underscore(component_name ${component_path})
-    
+
     # Add debug options based on build configuration (kit)
     if(BUILD_KIT STREQUAL test)
         # Exclude all components from the ALL target.
@@ -135,7 +135,6 @@ macro(spl_create_component)
         set(_component_doc_file ${_component_doc_dir}/index.rst)
         set(_component_test_junit_xml ${CMAKE_CURRENT_BINARY_DIR}/junit.xml)
         set(_component_reports_dir ${CMAKE_CURRENT_BINARY_DIR}/reports)
-        set(_autoconf_json_file ${AUTOCONF_JSON})
 
         # Create component docs target if there is an index.rst file in the component's doc directory
         if(EXISTS ${_component_doc_file})
@@ -150,7 +149,6 @@ macro(spl_create_component)
             set(_docs_config_json ${SPHINX_OUTPUT_DIR}/config.json)
             file(RELATIVE_PATH _rel_component_doc_dir ${SPHINX_SOURCE_DIR} ${_component_doc_dir})
             file(WRITE ${_docs_config_json} "{
-                \"generated_rst_content\": \".. toctree::\\n    :maxdepth: 2\\n\\n    /${_rel_component_doc_dir}/index\",
                 \"component_doc_dir\": \"${_rel_component_doc_dir}\",
                 \"include_patterns\": [\"${_rel_component_doc_dir}/**\",\"${_rel_sphinx_output_dir}/**\"]
             }")
@@ -160,12 +158,11 @@ macro(spl_create_component)
             add_custom_target(
                 ${component_name}_docs
                 COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR}
-                COMMAND ${CMAKE_COMMAND} -E env SPHINX_BUILD_CONFIGURATION_FILE=${_docs_config_json} AUTOCONF_JSON_FILE=${_autoconf_json_file} VARIANT=${VARIANT} -- sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
+                COMMAND ${CMAKE_COMMAND} -E remove_directory ${SPHINX_OUTPUT_DIR}/html
+                COMMAND ${CMAKE_COMMAND} -E env SPHINX_BUILD_CONFIGURATION_FILE=${_docs_config_json} AUTOCONF_JSON_FILE=${AUTOCONF_JSON} VARIANT=${VARIANT} -- sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
                 BYPRODUCTS ${SPHINX_OUTPUT_INDEX_HTML}
             )
 
-            add_dependencies(docs ${component_name}_docs)
-
             if(TEST_SOURCES)
                 set(SPHINX_OUTPUT_DIR ${_component_reports_dir})
                 file(RELATIVE_PATH _rel_sphinx_output_dir ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_DIR})
@@ -175,35 +172,8 @@ macro(spl_create_component)
                 # create the config.json file. This is exported as SPHINX_BUILD_CONFIGURATION_FILE env variable
                 set(_reports_config_json ${SPHINX_OUTPUT_DIR}/config.json)
 
-                # create the test_spec.rst file
-                set(_unit_test_spec_rst ${SPHINX_OUTPUT_DIR}/unit_test_spec.rst)
-                file(RELATIVE_PATH _rel_unit_test_spec_rst ${SPHINX_SOURCE_DIR} ${_unit_test_spec_rst})
-                file(WRITE ${_unit_test_spec_rst} "
-Unit Test Specification
-=======================
-
-.. needtable::
-   :filter: type == 'test'
-   :columns: id, title, tests, results
-   :style: table
-
-")
-
-                # create the unit_test_results.rst file
-                set(_unit_test_results_rst ${SPHINX_OUTPUT_DIR}/unit_test_results.rst)
-                file(RELATIVE_PATH _rel_unit_test_results_rst ${SPHINX_SOURCE_DIR} ${_unit_test_results_rst})
-                file(WRITE ${_unit_test_results_rst} "
-Unit Test Results
-=================
-
-.. test-report:: Unit Test Results
-    :id: TEST_RESULT
-    :file: {{ component_test_junit_xml }}
-
-")
-                set(_component_doxyfile ${SPHINX_OUTPUT_DIR}/Doxyfile)
-
                 # generate Doxyfile from template
+                set(_component_doxyfile ${SPHINX_OUTPUT_DIR}/Doxyfile)
                 set(DOXYGEN_PROJECT_NAME "Doxygen Documentation")
                 set(DOXYGEN_OUTPUT_DIRECTORY ${SPHINX_OUTPUT_DIR}/doxygen)
                 set(DOXYGEN_INPUT "${_component_dir}/src ${_component_dir}/test ${KCONFIG_OUT_DIR}")
@@ -217,8 +187,8 @@ Unit Test Results
                 file(RELATIVE_PATH _rel_component_doxysphinx_index_rst ${SPHINX_SOURCE_DIR} ${DOXYGEN_OUTPUT_DIRECTORY}/html/index)
 
                 file(WRITE ${_reports_config_json} "{
-                    \"generated_rst_content\": \".. toctree::\\n    :maxdepth: 2\\n\\n    /${_rel_component_doc_dir}/index\\n    /${_rel_unit_test_spec_rst}\\n    /${_rel_unit_test_results_rst}\\n    /${_rel_component_doxysphinx_index_rst}\",
-                    \"component_doc_dir\": \"${_rel_component_doc_dir}\", 
+                    \"component_doc_dir\": \"${_rel_component_doc_dir}\",
+                    \"component_reports_dir\": \"${SPHINX_OUTPUT_DIR}\",
                     \"component_test_junit_xml\": \"${_component_test_junit_xml}\",
                     \"include_patterns\": [\"${_rel_component_doc_dir}/**\",\"${_rel_sphinx_output_dir}/**\"]
                 }")
@@ -237,7 +207,7 @@ Unit Test Results
                     COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR}/doxygen
                     COMMAND doxygen ${_rel_component_doxyfile}
                     COMMAND doxysphinx build ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR} ${_rel_component_doxyfile}
-                    COMMAND ${CMAKE_COMMAND} -E env SPHINX_BUILD_CONFIGURATION_FILE=${_reports_config_json} AUTOCONF_JSON_FILE=${_autoconf_json_file} VARIANT=${VARIANT} -- sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
+                    COMMAND ${CMAKE_COMMAND} -E env SPHINX_BUILD_CONFIGURATION_FILE=${_reports_config_json} AUTOCONF_JSON_FILE=${AUTOCONF_JSON} VARIANT=${VARIANT} -- sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
                     BYPRODUCTS ${SPHINX_OUTPUT_INDEX_HTML}
                     DEPENDS ${TEST_OUT_JUNIT} ${COV_OUT_HTML}
                 )
@@ -248,11 +218,37 @@ Unit Test Results
     endif()
 endmacro()
 
+macro(_spl_create_docs_target)
+    # The Sphinx source directory is always the project root
+    set(SPHINX_SOURCE_DIR ${PROJECT_SOURCE_DIR})
+    set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs)
+    set(SPHINX_OUTPUT_HTML_DIR ${SPHINX_OUTPUT_DIR}/html)
+    set(SPHINX_OUTPUT_INDEX_HTML ${SPHINX_OUTPUT_HTML_DIR}/index.html)
+
+    # create the config.json file. This is exported as SPHINX_BUILD_CONFIGURATION_FILE env variable
+    set(_docs_config_json ${SPHINX_OUTPUT_DIR}/config.json)
+    file(RELATIVE_PATH _rel_sphinx_output_dir ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_DIR})
+    file(WRITE ${_docs_config_json} "{
+            \"include_patterns\": [\"${_rel_sphinx_output_dir}/**\"]
+        }")
+
+    # add the generated files as dependency to cmake configure step
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${_docs_config_json})
+    add_custom_target(
+        docs
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR}
+        COMMAND ${CMAKE_COMMAND} -E remove_directory ${SPHINX_OUTPUT_DIR}/html
+        COMMAND ${CMAKE_COMMAND} -E env SPHINX_BUILD_CONFIGURATION_FILE=${_docs_config_json} AUTOCONF_JSON_FILE=${AUTOCONF_JSON} VARIANT=${VARIANT} -- sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
+        BYPRODUCTS ${SPHINX_OUTPUT_INDEX_HTML}
+    )
+endmacro()
+
 macro(_spl_set_coverage_create_overall_report_is_necessary)
     set(_SPL_COVERAGE_CREATE_OVERALL_REPORT_IS_NECESSARY TRUE PARENT_SCOPE)
 endmacro(_spl_set_coverage_create_overall_report_is_necessary)
 
 set(COV_OUT_JSON coverage.json)
+
 function(_spl_coverage_create_overall_report)
     if(_SPL_COVERAGE_CREATE_OVERALL_REPORT_IS_NECESSARY)
         set(COV_OUT_VARIANT_HTML reports/coverage/index.html)
@@ -318,20 +314,24 @@ macro(_spl_add_test_suite PROD_SRC TEST_SOURCES)
     set(TEST_OUT_JUNIT junit.xml)
     add_custom_command(
         OUTPUT ${TEST_OUT_JUNIT}
+
         # Wipe all gcda files before the test executable recreates them
         COMMAND python ${SPL_CORE_PYTHON_DIRECTORY}/gcov_maid/gcov_maid.py --working-dir . --wipe-all-gcda
+
         # Run the test executable, generate JUnit report and return 0 independent of the test result
         COMMAND ${CMAKE_CTEST_COMMAND} ${CMAKE_CTEST_ARGUMENTS} --output-junit ${TEST_OUT_JUNIT} || ${CMAKE_COMMAND} -E true
         DEPENDS ${exe_name}
     )
 
     set(GLOBAL_COMPONENTS_COVERAGE_JSON_LIST "${GLOBAL_COMPONENTS_COVERAGE_JSON_LIST};${CMAKE_CURRENT_BINARY_DIR}/${COV_OUT_JSON}" CACHE INTERNAL "List of all ${COV_OUT_JSON} files")
-    
+
     # Create coverage report
     add_custom_command(
         OUTPUT ${COV_OUT_JSON}
+
         # Wipe orphaned gcno files before gcovr searches for them
         COMMAND python ${SPL_CORE_PYTHON_DIRECTORY}/gcov_maid/gcov_maid.py --working-dir . --wipe-orphaned-gcno
+
         # Run gcovr to generate coverage json for the component
         COMMAND gcovr --root ${CMAKE_SOURCE_DIR} --json --output ${COV_OUT_JSON} ${GCOVR_ADDITIONAL_OPTIONS} ${CMAKE_CURRENT_BINARY_DIR}
         DEPENDS ${TEST_OUT_JUNIT}

diff --git a/cmake/spl.cmake b/cmake/spl.cmake
@@ -71,8 +71,8 @@ elseif(BUILD_KIT STREQUAL test)
     list(APPEND CMAKE_CTEST_ARGUMENTS "--output-on-failure")
 
     add_custom_target(coverage)
-    add_custom_target(docs)
     add_custom_target(reports)
+    _spl_create_docs_target()
 else()
     message(FATAL_ERROR "Invalid BUILD_KIT selected!")
 endif(BUILD_KIT STREQUAL prod)

diff --git a/docs/internals/index.rst b/docs/internals/index.rst
@@ -71,19 +71,19 @@ Build kit *test*
    Build kit 'test' shall provide a build target 'unittests', that executes all tests of all SW components.
 
 .. req:: Support Creation of Documentation
-   :status: open
+   :status: done
 
    Build kit 'test' shall provide a build target '<component>_docs', that creates documentation of a SW component.
    Precondition of this build target is the existence of a doc folder inside the component's folder containing at
    least a conf.py.
 
 .. req:: Support Documentation
-   :status: open
+   :status: done
 
    Build kit 'test' shall provide a build target 'docs', that creates the documentation of all SW components.
 
 .. req:: Support Creation of a Component Report
-   :status: open
+   :status: done
 
    Build kit 'test' shall provide a build target '<component>_report', that creates a report of a SW component containing
    the documentation, test specification and all test results.
@@ -96,13 +96,13 @@ Build kit *test*
    SPL Core shall always start the docs target for generating the documentation and let sphinx-build handle the dependencies.
 
 .. req:: Configurable Sphinx Output
-   :status: open
+   :status: done
 
    The documentation shall be configurable. One should be able to generate the variant specific documentation, i.e.,
    only the variant specific components and their features shall be part of the documentation.
 
 .. req:: Project Documentation
-   :status: open
+   :status: done
 
    The project's index.rst file shall be static but changeable and configurable.
 
@@ -220,3 +220,20 @@ Component Reports CMake Target
 * we need to copy Doxyfile from the docs folder and then we have to update the paths where Doxyfile should find the sources
 * we need to call sphinx-build "pipenv run sphinx-build -b html . build/<Variant>/test/src/<Component>/reports/html"
     * source directory is always a projet root directory and output directory is build/<Variant>/test/src/<Component>/reports/
+
+
+Overall docs CMake Target
+-------------------------
+
+Overall docs will be created automatically by the target ``docs`` if there is an index.rst file in the root of the project ``doc`` directory.
+The files included in the ``doc`` folder and inside each component's ``doc`` folder are part of the overall documentation. Therefore, there will be no traceability to IDs from ``src`` or ``test``.
+
+Execution steps: 
+
+* we need to create an index.rst file which includes
+    * software requirements rst file
+    * software architecture rst file
+* we need to call sphinx-build "pipenv run sphinx-build -b html . build/<Variant>/test/doc/html"
+    * source directory is always a projet root directory and output directory is build/<Variant>/test/doc/
+
+
diff --git a/src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/extensions.json b/src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/extensions.json
@@ -12,6 +12,7 @@
             "ms-python.vscode-pylance",
             "ms-python.python",
             "donjayamanne.python-environment-manager",
-            "felipecaputo.git-project-manager"
+            "felipecaputo.git-project-manager",
+            "ms-vscode.powershell"
         ]
 }
diff --git a/src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/launch.json b/src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/launch.json
@@ -30,9 +30,7 @@
                 "debug-test"
             ],
             "console": "integratedTerminal",
-            "env": {
-                "PYTEST_ADDOPTS": "--no-cov"
-            },
+            "env": {},
             "justMyCode": false
         }
     ]

diff --git a/src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/settings.json b/src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/settings.json
@@ -1,21 +1,17 @@
 {
     "python.testing.pytestEnabled": true,
-    "python.testing.unittestEnabled": false,
-    "python.formatting.provider": "black",
-    "python.formatting.blackArgs": [
-        "--line-length",
-        "240"
+    "python.testing.pytestArgs": [
+        "test"
     ],
-    "python.formatting.blackPath": "black",
-    "python.linting.enabled": true,
-    "python.linting.flake8Enabled": true,
-    "python.linting.flake8Args": [
-        "--ignore=W293"
+    "python.testing.unittestEnabled": false,
+    "python.analysis.extraPaths": [
+        "test"
     ],
     "cmake.configureOnOpen": false,
     "cmake.buildDirectory": "${workspaceFolder}/build/${variant:variant}/${buildKit}",
     "cmake.configureSettings": {
-        "BUILD_KIT": "${buildKit}"
+        "BUILD_KIT": "${buildKit}",
+        "CMAKE_MESSAGE_LOG_LEVEL": "STATUS"
     },
     "cmake.generator": "Ninja",
     "cmake.debugConfig": {
@@ -25,7 +21,10 @@
     },
     "cmake.configureOnEdit": false,
     "cmake.buildBeforeRun": false,
-    "cmake.environment": {},
+    "cmake.environment": {
+        "PIPENV_VERBOSITY": "-1",
+        "PIPENV_VENV_IN_PROJECT": "1"
+    },
     "cmake.buildToolArgs": [],
     "git.ignoreLimitWarning": true,
     "C_Cpp.errorSquiggles": "enabled",
@@ -38,14 +37,10 @@
         "Jenkinsfile": "groovy",
         "*.py": "python"
     },
-    "files.exclude": {
-        "**/.git": true,
-        "**/.DS_Store": true,
-        "**/Thumbs.db": true
-    },
     "git.repositoryScanMaxDepth": 3,
     "git-graph.maxDepthOfRepoSearch": 3,
     "[python]": {
         "editor.defaultFormatter": "ms-python.black-formatter"
-    }
+    },
+    "esbonio.sphinx.confDir": ""
 }
diff --git a/src/project_creator/templates/project/{{cookiecutter.name}}/Pipfile b/src/project_creator/templates/project/{{cookiecutter.name}}/Pipfile
@@ -4,25 +4,30 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-conan = {version="==1.59.0"}
 cookiecutter = "*"
 gcovr = "*"
 hammocking = "*"
 kconfiglib = "*"
+jinja2 = "*"
 pytest = "*"
-pytest-cov = "*"
-pipenv = "*"
+pytest-env = "*"
+testfixtures = "*"
+junitparser = "*"
+mashumaro = "*"
+loguru = "*"
+black = "*"
+flake8 = "*"
 sphinx = "*"
 sphinx-rtd-theme = "*"
 sphinxcontrib-mermaid = "*"
 sphinx-needs = "*"
-sphinxcontrib-plantuml = "*"
 sphinx-test-reports = "*"
 doxysphinx = "*"
-
-[dev-packages]
-flake8 = "*"
-black = "*"
+sphinx-rtd-size = "*"
+sphinxcontrib-datatemplates = "*"
+pyelftools = "*"
+sphinxcontrib-plantuml = "*"
+pipenv = "*"
 
 [requires]
 python_version = "3.11"