docs with external link (#22)

Author: MaximilianSoerenPollak

.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 }}

docs/BUILD

@@ -0,0 +1,60 @@
+# *******************************************************************************
+# 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": "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",
+                    "id_prefix": "score_",
+                },
+            ],
+        },
+    ],
+    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",
+#         },
+#     ],
+# },

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

docs/index.rst

@@ -0,0 +1,29 @@
+..
+   # *******************************************************************************
+   # 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
+   This is a link to an external need inside the 'score' documentation
+   :need:`SCORE_gd_req__req__attr_safety`
+

src/extensions/score_metamodel/__init__.py

@@ -77,7 +77,10 @@ def _run_checks(app: Sphinx, exception: Exception | None) -> None:
     if exception:
         return
 
-    needs_all_needs = SphinxNeedsData(app.env).get_needs_view()
+    # 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)
+    )
 
     logger.debug(f"Running checks for {len(needs_all_needs)} needs")