From 3221137195eddfe05ba11f052beb7f67c7a9b941 Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Mon, 12 May 2025 16:14:06 +0200 Subject: [PATCH 1/7] Adding docs example --- docs/BUILD | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 54 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 35 ++++++++++++++++++++++++++++ 3 files changed, 151 insertions(+) create mode 100644 docs/BUILD create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/docs/BUILD b/docs/BUILD new file mode 100644 index 000000000..ed55331f7 --- /dev/null +++ b/docs/BUILD @@ -0,0 +1,62 @@ +# ******************************************************************************* +# Copyright (c) 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 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +load("@aspect_rules_py//py:defs.bzl", "py_library") +load("//:docs.bzl", "docs") + +# Creates all documentation targets: +# - `docs:incremental` for building docs incrementally at runtime +# - `docs:live_preview` for live preview in the browser without an IDE +# - `docs:ide_support` for creating python virtualenv for IDE support +# - `docs:docs` for building documentation at build-time + +docs( + conf_dir = "docs", + docs_targets = [ + { + "suffix": "", # local without external needs + }, + { + "suffix": "latest", # latest main branch documentation build + "external_needs_info": [ + { + "base_url": "https://eclipse-score.github.io/score/main/", + "json_url": "https://eclipse-score.github.io/score/main/needs.json", + "version": "0.1", + }, + ], + }, + ], + source_dir = "docs", + source_files_to_scan_for_needs_links = [ + # Note: you can add filegroups, globs, or entire targets here. + "//src:score_extension_files", + ], +) + +# ╭───────────────────────────────────────╮ +# │ This is commented out until local │ +# │ multi-repo testing is implemented │ +# ╰───────────────────────────────────────╯ + +# { +# "suffix": "release", # The version imported from MODULE.bazel +# "target": ["@score_platform//docs:docs"], +# "external_needs_info": [ +# { +# "base_url": "https://eclipse-score.github.io/score/pr-980/", +# "json_path": "/score_platform~/docs/docs/_build/html/needs.json", +# "version": "0.1", +# }, +# ], +# }, diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..fbef18a80 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,54 @@ +# ******************************************************************************* +# Copyright (c) 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 +# +# SPDX-License-Identifier: Apache-2.0 +# ******************************************************************************* + +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "Simple Example Project" +author = "S-CORE" +version = "0.1" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + + +extensions = [ + "sphinx_design", + "sphinx_needs", + "sphinxcontrib.plantuml", + "score_plantuml", + "score_metamodel", + "score_draw_uml_funcs", + "score_source_code_linker", + "score_layout", +] + +exclude_patterns = [ + # The following entries are not required when building the documentation via 'bazel + # build //docs:docs', as that command runs in a sandboxed environment. However, when + # building the documentation via 'bazel run //docs:incremental' or esbonio, these + # entries are required to prevent the build from failing. + "bazel-*", + ".venv_docs", +] + +templates_path = ["templates"] + +# Enable numref +numfig = True diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..c1f2f749f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,35 @@ +.. + # ******************************************************************************* + # Copyright (c) 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 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Hello World +================= +This is a simple example of a documentation page using the `docs` tool. + +.. stkh_req:: TestTitle + :id: stkh_req__test_requirement + :status: valid + :safety: QM + :rationale: A simple requirement we need to enable a documentation build + :reqtype: Functional + + Some content to make sure we also can render this + + +.. std_req:: External Link Test Req + :id: std_req__iso26262__testing + :status: valid + :safety: QM + :links: gd_req__req__attr_safety + + This is some test content to show a link to the 'score' documentation From 2cb46ec9b8a7a78a21ec943f5ccb3041ed88ea79 Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Mon, 12 May 2025 16:16:13 +0200 Subject: [PATCH 2/7] Fix workflow --- .github/workflows/license_check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/license_check.yml b/.github/workflows/license_check.yml index 51a9ffdd7..7d80eecd8 100644 --- a/.github/workflows/license_check.yml +++ b/.github/workflows/license_check.yml @@ -28,6 +28,6 @@ jobs: uses: eclipse-score/cicd-workflows/.github/workflows/license-check.yml@main with: repo-url: "${{ github.server_url }}/${{ github.repository }}" - bazel-target: "//src:license-check" + bazel-target: "run //src:license-check" secrets: dash-api-token: ${{ secrets.ECLIPSE_GITLAB_API_TOKEN }} From 3f4a619eaa371869e81d7a924a96966779837ec2 Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Mon, 12 May 2025 16:49:19 +0200 Subject: [PATCH 3/7] Adapt example & add external needs filter Added filtering of external needs to ignore them from being checked by local checks. Added id_prefix to the example Changed example to make it simpler --- docs/BUILD | 1 + docs/index.rst | 10 ++-------- src/extensions/score_metamodel/__init__.py | 2 +- 3 files changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/BUILD b/docs/BUILD index ed55331f7..8e4b8a326 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -33,6 +33,7 @@ docs( "base_url": "https://eclipse-score.github.io/score/main/", "json_url": "https://eclipse-score.github.io/score/main/needs.json", "version": "0.1", + "id_prefix": "score_", }, ], }, diff --git a/docs/index.rst b/docs/index.rst index c1f2f749f..10df3f53d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,12 +24,6 @@ This is a simple example of a documentation page using the `docs` tool. :reqtype: Functional Some content to make sure we also can render this + This is a link to an external need inside the 'score' docuemntation + :need:`SCORE_gd_req__req__attr_safety` - -.. std_req:: External Link Test Req - :id: std_req__iso26262__testing - :status: valid - :safety: QM - :links: gd_req__req__attr_safety - - This is some test content to show a link to the 'score' documentation diff --git a/src/extensions/score_metamodel/__init__.py b/src/extensions/score_metamodel/__init__.py index c69e5d6e2..3d94cb7f0 100644 --- a/src/extensions/score_metamodel/__init__.py +++ b/src/extensions/score_metamodel/__init__.py @@ -77,7 +77,7 @@ def _run_checks(app: Sphinx, exception: Exception | None) -> None: if exception: return - needs_all_needs = SphinxNeedsData(app.env).get_needs_view() + needs_all_needs = SphinxNeedsData(app.env).get_needs_view().filter_is_external(False) logger.debug(f"Running checks for {len(needs_all_needs)} needs") From d82593adec5b5bde0776b4ff2fa8e18c4a882970 Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Mon, 12 May 2025 16:52:52 +0200 Subject: [PATCH 4/7] Remove 'local' build as it doesn't make sense --- docs/BUILD | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/BUILD b/docs/BUILD index 8e4b8a326..0c2ce22a7 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -23,9 +23,6 @@ load("//:docs.bzl", "docs") docs( conf_dir = "docs", docs_targets = [ - { - "suffix": "", # local without external needs - }, { "suffix": "latest", # latest main branch documentation build "external_needs_info": [ From 6153c3b714befce79baf7a40294af93755c7687b Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Mon, 12 May 2025 16:59:28 +0200 Subject: [PATCH 5/7] Formatting --- src/extensions/score_metamodel/__init__.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/extensions/score_metamodel/__init__.py b/src/extensions/score_metamodel/__init__.py index 3d94cb7f0..f755b0477 100644 --- a/src/extensions/score_metamodel/__init__.py +++ b/src/extensions/score_metamodel/__init__.py @@ -77,7 +77,9 @@ def _run_checks(app: Sphinx, exception: Exception | None) -> None: if exception: return - needs_all_needs = SphinxNeedsData(app.env).get_needs_view().filter_is_external(False) + needs_all_needs = ( + SphinxNeedsData(app.env).get_needs_view().filter_is_external(False) + ) logger.debug(f"Running checks for {len(needs_all_needs)} needs") From 6dc30f13742c80d8e36b4a617a3ddfb8fc7536c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20S=C3=B6ren=20Pollak?= Date: Mon, 12 May 2025 17:00:41 +0200 Subject: [PATCH 6/7] Update src/extensions/score_metamodel/__init__.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Maximilian Sören Pollak --- src/extensions/score_metamodel/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/extensions/score_metamodel/__init__.py b/src/extensions/score_metamodel/__init__.py index f755b0477..2e8321ea5 100644 --- a/src/extensions/score_metamodel/__init__.py +++ b/src/extensions/score_metamodel/__init__.py @@ -77,6 +77,7 @@ def _run_checks(app: Sphinx, exception: Exception | None) -> None: if exception: return + # Filter out external needs, as checks are only intended to be run on internal needs. needs_all_needs = ( SphinxNeedsData(app.env).get_needs_view().filter_is_external(False) ) From d7aa6930ac82efe8ad25252c4c480a5a36dec31f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20S=C3=B6ren=20Pollak?= Date: Mon, 12 May 2025 17:00:47 +0200 Subject: [PATCH 7/7] Update docs/index.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Maximilian Sören Pollak --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 10df3f53d..b23acaa27 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,6 @@ This is a simple example of a documentation page using the `docs` tool. :reqtype: Functional Some content to make sure we also can render this - This is a link to an external need inside the 'score' docuemntation + This is a link to an external need inside the 'score' documentation :need:`SCORE_gd_req__req__attr_safety`