refactor docs target to use generic index rst

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
     "python.testing.pytestEnabled": true,
     "python.testing.unittestEnabled": false,
-    "python.formatting.provider": "none",
+    "python.formatting.provider": "black",
     "python.formatting.blackArgs": [
         "--line-length",
         "240"
@@ -38,5 +38,6 @@
     "restructuredtext.preview.docutils.disabled": true,
     "[python]": {
         "editor.defaultFormatter": "ms-python.black-formatter"
-    }
+    },
+    "esbonio.sphinx.confDir": ""
 }

cmake/common.cmake

@@ -82,6 +82,7 @@ macro(spl_create_component)
     _spl_slash_to_underscore(component_name ${component_path})
     add_library(${component_name} OBJECT ${SOURCES})
 
+    # Add debug options based on build configuration (kit)
     if(BUILD_KIT STREQUAL test)
         target_compile_options(${component_name} PRIVATE ${VARIANT_ADDITIONAL_COMPILE_C_FLAGS} -ggdb --coverage)
     else()
@@ -99,25 +100,45 @@ macro(spl_create_component)
     set(target_include_directories__INCLUDES ${target_include_directories__INCLUDES} PARENT_SCOPE)
 
     if(BUILD_KIT STREQUAL test)
+        # Create component unittests target
         if(TEST_SOURCES)
             set(exe_name ${component_name}_test)
             _spl_add_test_suite("${SOURCES}" ${TEST_SOURCES})
         endif()
 
-        set(SPHINX_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/doc)
-
-        if(EXISTS ${SPHINX_SOURCE_DIR}/conf.py)
+        # Create component docs target if there is an index.rst file in the component doc directory
+        set(_component_doc_dir ${CMAKE_CURRENT_LIST_DIR}/doc)
+        set(_component_doc_file ${_component_doc_dir}/index.rst)
+        if(EXISTS ${_component_doc_file})
+            # The Sphinx source directory is always the project root
+            set(SPHINX_SOURCE_DIR ${PROJECT_SOURCE_DIR})
             set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc)
             set(SPHINX_OUTPUT_HTML_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc/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 _build_docs_dir ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_DIR})
+            file(RELATIVE_PATH _component_doc_dir ${SPHINX_SOURCE_DIR} ${_component_doc_dir})
+            file(WRITE ${_docs_config_json} "{\"build_docs_dir\": \"${_build_docs_dir}\", \"component_doc_dir\": \"${_component_doc_dir}\"}")
+            # create the index.rst file
+            set(_docs_index_rst ${SPHINX_OUTPUT_DIR}/index.rst)
+            file(WRITE ${_docs_index_rst} "Index in build directory
+========================
+
+.. toctree::
+    
+    /{{ component_doc_dir }}/index
+")
             add_custom_target(
                 ${component_name}_docs
                 COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_OUTPUT_DIR}
-                COMMAND sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
+                COMMAND ${CMAKE_COMMAND} -E env SPHINX_BUILD_CONFIGURATION_FILE=${_docs_config_json} sphinx-build -b html ${SPHINX_SOURCE_DIR} ${SPHINX_OUTPUT_HTML_DIR}
                 BYPRODUCTS ${SPHINX_OUTPUT_INDEX_HTML}
             )
+
             add_dependencies(docs ${component_name}_docs)
         endif()
+
     endif()
 endmacro()
 

docs/design/index.rst

@@ -133,4 +133,53 @@ Folder structure for report creation
           index.rst
         conf.py
         index.rst
-
+
+
+Sphinx Build Configuration
+**************************
+
+Sphnix build required configurtaion file(conf.py) and main rst(index.rst) file are located in same folder.
+Because of this:
+  * we need conf.py and index.rst in root directory
+  * index.rst file dynamically includes the target index.rst
+  * conf.py needs to read a configuration file(config.json) to be able to find all the relevant files for the current CMake docs target 
+  * 
+
+conf.py
+^^^^^^^
+  * conf.py is a static file and we don't know the path of config.json file, we need to get the path to it as an environment variable.
+  * we should check, if environment variable(SPHINX_BUILD_CONFIGURATION_FILE) exists just load the content and store into the html_context(https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context)
+
+index.rst
+^^^^^^^^^
+  * this file just includes the target index.rst depends on docs CMake target.
+
+
+Component Docs CMake Target
+***************************
+
+A component docs target ``<component>_docs`` will be created automatically if there is an index.rst file in the component ``doc`` directory.
+Only the files included in the ``doc`` folder are part of the report, so there will be no traceability to IDs from ``src`` or ``test``.
+
+Execution steps: 
+
+* we need to create config.json
+* we need to create an index.rst which includes
+    * component detailed design rst file
+* we need to call sphinx-build "pipenv run sphinx-build -b html . build/<Variant>/test/src/<Component>/docs/html"
+    * source directory is always a projet root directory and output directory is build/<Variant>/test/src/<Component>/docs/
+
+
+Component Reports CMake Target
+******************************
+
+* this target depends on unittests target
+* we need to create config.json
+* we need to create an index.rst which includes
+    * component detailed design rst file
+    * component test results rst file
+    * component doxygen rst file
+* we need to create a test_results.rst file to include the componenet junit test results.
+* 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/

docs/test_report_template.txt

@@ -0,0 +1,49 @@
+**Statistics**
+
+| Test cases: :need_count:`'{id}' in tags and type=='{case_need}'`
+| Failed test cases: :need_count:`'{id}' in tags and 'failure' == result and type=='{case_need}'`
+| Passed test cases: :need_count:`'{id}' in tags and 'passed' == result and type=='{case_need}'`
+| Skipped test cases: :need_count:`'{id}' in tags and 'skipped' == result and type=='{case_need}'`
+| Test suites: :need_count:`'{id}' in tags and type=='{suite_need}'`
+
+**Failed test cases**:
+
+.. needtable::
+   :filter: type == '{case_need}' and 'failure' == result
+   :columns: id, title, is resulted from
+   :style: table
+
+**Passed test cases**:
+
+.. needtable::
+   :filter: type == '{case_need}' and 'passed' == result
+   :columns: id, title, is resulted from
+   :style: table
+
+**Skipped test cases**:
+
+.. needtable::
+   :filter: type == '{case_need}' and 'skipped' == result
+   :columns: id, title, is resulted from
+   :style: table
+
+**New table**:
+
+.. needtable::
+   :filter: type == 'test'
+   :columns: id, title, specified by, test results
+   :style: table
+
+**Imported data**
+
+
+.. {file_type}:: {title}
+   :id: {id}{links_string}
+   :tags: {tags}
+   :file: {file}
+   :auto_suites:
+   :auto_cases:
+
+   {content}
+
+

src/project_creator/templates/project/cookiecutter.json

@@ -7,5 +7,8 @@
       "flavor": "flavor",
       "subsystem": "subsystem"
     }
-  }
+  },
+  "_copy_without_render": [
+        "*.rst"
+    ]
 }

src/project_creator/templates/project/{{cookiecutter.name}}/conf.py

@@ -6,6 +6,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import json
+import os
+
+
 project = "Project"
 copyright = "2023"
 author = "RMT"
@@ -16,7 +20,7 @@
 
 extensions = []
 exclude_patterns = [".git", ".venv", "build/modules", "**/.venv"]
-#include_patterns = ["**/doc"]
+# include_patterns = ["**/doc"]
 
 
 # mermaid config - @see https://pypi.org/project/sphinxcontrib-mermaid/
@@ -25,10 +29,84 @@
 # sphinx_needs
 extensions.append("sphinx_needs")
 
+
+# needs_types - this option allows the setup of own need types like bugs, user_stories and more.
+
+needs_types = [
+    dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"),
+    dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"),
+    dict(directive="impl", title="Implementation", prefix="I_", color="#DF744A", style="node"),
+    dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node"),
+    # Kept for backwards compatibility
+    dict(directive="need", title="Need", prefix="N_", color="#9856a5", style="node"),
+    dict(directive="image", title="Image", prefix="IMG_", color="#FFCC00", style="node"),
+]
+
+# Define own options
+needs_extra_options = ["integrity", "assignee", "version"]
+
+# Define own link types
+
+needs_extra_links = [
+    {"option": "checks", "incoming": "is checked by", "outgoing": "checks"},
+    {"option": "implements", "incoming": "is implemented by", "outgoing": "implements"},
+    {"option": "tests", "incoming": "is tested by", "outgoing": "tests requirement(s)"},
+    {"option": "results", "incoming": "is resulted from", "outgoing": "test results"},
+    {"option": "requirement", "incoming": "specification", "outgoing": "requirement"},
+    {"option": "specified", "incoming": "tested by", "outgoing": "specified by"},
+]
+
+
+# sphinxcontrib-test-reports
+extensions.append("sphinxcontrib.test_reports")
+tr_report_template = "doc/test_report_template.txt"
+
 # The suffix of source filenames.
 source_suffix = [".rst"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
+
+# Hide hyper link which leeds to the source of page displayed
+html_show_sourcelink = True
+
+html_theme_options = {
+    "canonical_url": "",
+    "analytics_id": "",  #  Provided by Google in your dashboard
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": True,
+    "logo_only": False,
+    "style_nav_header_background": "white",
+    # Toc options
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 6,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+# Check if the SPHINX_BUILD_CONFIGURATION_FILE environment variable exists
+# and if so, load the JSON file and set the 'html_context' variable
+if "SPHINX_BUILD_CONFIGURATION_FILE" in os.environ:
+    SPHINX_BUILD_CONFIGURATION_FILE = os.environ["SPHINX_BUILD_CONFIGURATION_FILE"]
+    with open(SPHINX_BUILD_CONFIGURATION_FILE, "r") as file:
+        html_context = json.load(file)
+
+
+def rstjinja(app, docname, source):
+    """
+    Render our pages as a jinja template for fancy templating goodness.
+    """
+    # Make sure we're outputting HTML
+    if app.builder.format != "html":
+        return
+    src = source[0]
+    rendered = app.builder.templates.render_string(src, app.config.html_context)
+    source[0] = rendered
+
+
+def setup(app):
+    app.connect("source-read", rstjinja)

src/project_creator/templates/project/{{cookiecutter.name}}/index.rst

@@ -1,8 +1,6 @@
-Welcome to Project documentation
-################################
+Index in project root
+=====================
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-   components/component/doc/index
+
+   {{ build_docs_dir }}/index.rst

src/project_creator/templates/project/{{cookiecutter.name}}/{% if cookiecutter.touch_components -%} components {%- endif %}/main/doc/index.rst

@@ -0,0 +1,4 @@
+Welcome to Main documentation
+#############################
+
+This is the documentation for the ``Main`` component.

tests/test_documentation.py

@@ -25,5 +25,6 @@ def test_build_docs(self):
             assert 0 == self.workspace.run_cmake_build(build_kit="test", target="docs").returncode
 
         assert build_dir_test.joinpath("components/component/doc/html/index.html").exists()
-        assert build_dir_test.joinpath("components/component/doc/html/design.html").exists()
+        assert build_dir_test.joinpath("components/component/doc/html/components/component/doc/index.html").exists()
+        assert build_dir_test.joinpath("components/component/doc/html/components/component/doc/design.html").exists()
         assert build_dir_test.joinpath("components/component/doc/html/_images/screenshot.png").exists()