From 2f7799d7fa69b03e8066bb8f1b4e251242a14616 Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Tue, 21 Oct 2025 15:38:07 +0200 Subject: [PATCH 1/2] Full documentation build Pulls in platform, docs_as_code, and process documentation. --- qnx_qemu/.bazelrc => .bazelrc | 0 qnx_qemu/.bazelversion => .bazelversion | 0 BUILD | 51 +++++++++++++++++++ MODULE.bazel | 31 ++++++++++++ docs/conf.py | 55 +++++++++++++++++++++ docs/index.rst | 23 +++++++++ full_docs.bzl | 65 +++++++++++++++++++++++++ 7 files changed, 225 insertions(+) rename qnx_qemu/.bazelrc => .bazelrc (100%) rename qnx_qemu/.bazelversion => .bazelversion (100%) create mode 100644 BUILD create mode 100644 MODULE.bazel create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 full_docs.bzl diff --git a/qnx_qemu/.bazelrc b/.bazelrc similarity index 100% rename from qnx_qemu/.bazelrc rename to .bazelrc diff --git a/qnx_qemu/.bazelversion b/.bazelversion similarity index 100% rename from qnx_qemu/.bazelversion rename to .bazelversion diff --git a/BUILD b/BUILD new file mode 100644 index 000000000..bd8f461e9 --- /dev/null +++ b/BUILD @@ -0,0 +1,51 @@ +# ******************************************************************************* +# Copyright (c) 2025 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("@score_docs_as_code//:docs.bzl", "docs") +load("@score_tooling//:defs.bzl", "copyright_checker", "setup_starpls", "use_format_targets") + +setup_starpls( + name = "starpls_server", + visibility = ["//visibility:public"], +) + +copyright_checker( + name = "copyright", + srcs = [ + "src", + "tests", + "//:BUILD", + "//:MODULE.bazel", + ], + config = "@score_tooling//cr_checker/resources:config", + template = "@score_tooling//cr_checker/resources:templates", + visibility = ["//visibility:public"], +) + + +# Add target for formatting checks +use_format_targets() + +docs( + source_dir = "docs", +) + +load("//:full_docs.bzl", "all_docs") + +all_docs( + subdocs = { + "@score_platform//:docs_sources": "platform", + "@score_docs_as_code//:docs_sources": "docs_as_code", + "@score_process//:docs_sources": "process", + }, +) diff --git a/MODULE.bazel b/MODULE.bazel new file mode 100644 index 000000000..4fac7708c --- /dev/null +++ b/MODULE.bazel @@ -0,0 +1,31 @@ +# ******************************************************************************* +# Copyright (c) 2025 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 +# ******************************************************************************* +module( + name = "reference_integration", + version = "0.1", +) +bazel_dep(name = "rules_pkg", version = "1.1.0") + +bazel_dep(name = "rules_python", version = "1.4.1") +python = use_extension("@rules_python//python/extensions:python.bzl", "python") +python.toolchain( + is_default = True, + python_version = "3.12", +) +use_repo(python) + +bazel_dep(name = "score_tooling", version = "1.0.1") +bazel_dep(name = "score_platform", version = "0.3.0") +bazel_dep(name = "score_process", version = "1.2.0") +bazel_dep(name = "score_docs_as_code", version = "1.4.0") +git_override(module_name = "score_docs_as_code", commit = "f74f2e7", remote = "https://github.com/eclipse-score/docs-as-code") # workaround until 1.4.1+ is released diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..8bcdbb8fe --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,55 @@ +# ******************************************************************************* +# 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 = "S-CORE Full Documentation" +project_url = "https://eclipse-score.github.io/module_template/" +project_prefix = "ALL_" +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..647bec98c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,23 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +All of S-CORE +============= + +.. toctree:: + :maxdepth: 2 + + docs_as_code/index + Platform + intro/index diff --git a/full_docs.bzl b/full_docs.bzl new file mode 100644 index 000000000..5f6b9413c --- /dev/null +++ b/full_docs.bzl @@ -0,0 +1,65 @@ + +load("@rules_pkg//pkg:mappings.bzl", "pkg_files", "strip_prefix") +load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs") + +def _drop_path(path, prefix_count): + parts = path.split("/") + if len(parts) <= prefix_count: + return "" + return "/".join(parts[prefix_count:]) + +def _full_docs_impl(ctx): + # Generate symlinks to dependency documentation + output = [] + for tgt in ctx.attr.subdocs: + name = ctx.attr.subdocs[tgt] + for f in tgt.files.to_list(): + s = ctx.actions.declare_file(name + "/" + _drop_path(f.path,3)) + ctx.actions.symlink(output = s, target_file = f) + output.append(s) + + # Generate index with toctree + index = ctx.actions.declare_file("index.rst") + contents = "" + contents += "All of S-CORE\n" + contents += "=============\n\n" + contents += ".. toctree::\n" + contents += " :maxdepth: 2\n\n" + for tgt in ctx.attr.subdocs: + name = ctx.attr.subdocs[tgt] + contents += " " + name + "/index\n" + ctx.actions.write(output = index, content = contents) + output.append(index) + + return [DefaultInfo(files = depset(output))] + + +docs_combo = rule( + implementation = _full_docs_impl, + attrs = { + "subdocs": attr.label_keyed_string_dict(default = {}), + }, +) + + +def all_docs(subdocs ={}): + docs_combo( + name = "all_docs", + subdocs = subdocs, + ) + sphinx_docs( + name = "full_html", + srcs = [":all_docs"], + config = "docs/conf.py", + extra_opts = [ + #"-W", + "--keep-going", + "-T", # show more details in case of errors + "--jobs", + "auto", + ], + formats = ["html"], + sphinx = ":sphinx_build", + strip_prefix = "docs/", + visibility = ["//visibility:public"], + ) From 3d23207422d3fc36609ff72401d0b1b1613fe3e0 Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Fri, 31 Oct 2025 14:08:41 +0100 Subject: [PATCH 2/2] revise --- BUILD | 2 ++ docs/conf.py | 4 ++-- docs/index.rst | 11 ++++------ full_docs.bzl | 36 +++++++++++++++++++++++-------- full_docs/conf.py | 55 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 90 insertions(+), 18 deletions(-) create mode 100644 full_docs/conf.py diff --git a/BUILD b/BUILD index bd8f461e9..0c0a50b21 100644 --- a/BUILD +++ b/BUILD @@ -43,8 +43,10 @@ docs( load("//:full_docs.bzl", "all_docs") all_docs( + conf = "full_docs/conf.py", subdocs = { "@score_platform//:docs_sources": "platform", + ":docs_sources": "integration", "@score_docs_as_code//:docs_sources": "docs_as_code", "@score_process//:docs_sources": "process", }, diff --git a/docs/conf.py b/docs/conf.py index 8bcdbb8fe..e998a7c11 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,9 +20,9 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = "S-CORE Full Documentation" +project = "S-CORE Reference Integration" project_url = "https://eclipse-score.github.io/module_template/" -project_prefix = "ALL_" +project_prefix = "INT_" author = "S-CORE" version = "0.1" diff --git a/docs/index.rst b/docs/index.rst index 647bec98c..a2e25232c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,12 +12,9 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -All of S-CORE -============= +##################### +Reference Integration +##################### -.. toctree:: - :maxdepth: 2 +This is the reference integration of S-CORE. - docs_as_code/index - Platform - intro/index diff --git a/full_docs.bzl b/full_docs.bzl index 5f6b9413c..d15cdad3f 100644 --- a/full_docs.bzl +++ b/full_docs.bzl @@ -1,21 +1,34 @@ +"""Bazel rules for combining multiple Sphinx documentation sets into a unified documentation site.""" load("@rules_pkg//pkg:mappings.bzl", "pkg_files", "strip_prefix") load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs") -def _drop_path(path, prefix_count): +def _adapt_path(path): + """Adapt the file path by removing leading segments such that index.rst has no leading segments.""" parts = path.split("/") - if len(parts) <= prefix_count: - return "" - return "/".join(parts[prefix_count:]) + if parts[0] == "external": + # Necessary for files from other Bazel modules + parts = parts[3:] + else: + # Necessary for files in this module + parts = parts[1:] + return "/".join(parts) def _full_docs_impl(ctx): + """Implementation function for the docs_combo rule. + + This function aggregates multiple documentation targets by creating symlinks + to their files and generating a top-level index.rst with a table of contents + that references all subdocumentation. + """ # Generate symlinks to dependency documentation output = [] for tgt in ctx.attr.subdocs: name = ctx.attr.subdocs[tgt] for f in tgt.files.to_list(): - s = ctx.actions.declare_file(name + "/" + _drop_path(f.path,3)) + s = ctx.actions.declare_file(name + "/" + _adapt_path(f.path)) ctx.actions.symlink(output = s, target_file = f) + print("s.path: " + s.path + " f.path: " + f.path) output.append(s) # Generate index with toctree @@ -28,6 +41,7 @@ def _full_docs_impl(ctx): for tgt in ctx.attr.subdocs: name = ctx.attr.subdocs[tgt] contents += " " + name + "/index\n" + contents += "\nThis overview document is automatically generated.\n" ctx.actions.write(output = index, content = contents) output.append(index) @@ -37,12 +51,16 @@ def _full_docs_impl(ctx): docs_combo = rule( implementation = _full_docs_impl, attrs = { - "subdocs": attr.label_keyed_string_dict(default = {}), + "subdocs": attr.label_keyed_string_dict( + doc = "Dictionary mapping documentation targets to their display names", + default = {}, + ), }, ) -def all_docs(subdocs ={}): +def all_docs(subdocs = {}, conf = "full_docs/conf.py"): + """Macro to create a complete documentation build combining multiple doc sources.""" docs_combo( name = "all_docs", subdocs = subdocs, @@ -50,7 +68,7 @@ def all_docs(subdocs ={}): sphinx_docs( name = "full_html", srcs = [":all_docs"], - config = "docs/conf.py", + config = conf, extra_opts = [ #"-W", "--keep-going", @@ -60,6 +78,6 @@ def all_docs(subdocs ={}): ], formats = ["html"], sphinx = ":sphinx_build", - strip_prefix = "docs/", + strip_prefix = "full_docs/", visibility = ["//visibility:public"], ) diff --git a/full_docs/conf.py b/full_docs/conf.py new file mode 100644 index 000000000..8bcdbb8fe --- /dev/null +++ b/full_docs/conf.py @@ -0,0 +1,55 @@ +# ******************************************************************************* +# 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 = "S-CORE Full Documentation" +project_url = "https://eclipse-score.github.io/module_template/" +project_prefix = "ALL_" +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