Skip to content

Commit c1abd47

Browse files
MaximilianSoerenPollakMaximilianSoerenPollak
authored
Integrate functionality (#3)
Moved docs.bzl to root Added missing dotfiles Copied score_metamodel from score and discarded old local changes Small clean up of several files Renaming of 'tooling' -> 'src' Formatted code
1 parent bd41f29 commit c1abd47

38 files changed

Lines changed: 1137 additions & 345 deletions

‎.bazelrc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
build --java_language_version=17
2+
build --tool_java_language_version=17
3+
build --java_runtime_version=remotejdk_17
4+
build --tool_java_runtime_version=remotejdk_17
5+
6+
test --test_output=errors
7+
8+
# stop legacy behavior of creating __init__.py files
9+
build --incompatible_default_to_explicit_init_py
10+
11+
common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/
12+
common --registry=https://bcr.bazel.build

‎.bazelversion‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
7.4.0

‎.gitignore‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Commonly used for local settings and secrets
2+
.env
3+
4+
# Bazel
5+
bazel-*
6+
MODULE.bazel.lock
7+
user.bazelrc
8+
9+
# Ruff
10+
.ruff_cache
11+
12+
# docs:incremental and docs:ide_support build artifacts
13+
/_build*
14+
15+
# Vale - editorial style guide
16+
.vale.ini
17+
styles/
18+
19+
# direnv - folder-specific bash configuration
20+
.envrc
21+
22+
# Python
23+
.venv
24+
__pycache__/
25+
/.coverage

‎.yamlfmt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
formatter:
2+
type: basic
3+
retain_line_breaks: true

‎BUILD‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
load("@score_cr_checker//:cr_checker.bzl", "copyright_checker")
15+
16+
copyright_checker(
17+
name = "copyright",
18+
srcs = [
19+
"process-docs",
20+
"src",
21+
"//:BUILD",
22+
"//:MODULE.bazel",
23+
],
24+
config = "@score_cr_checker//resources:config",
25+
template = "@score_cr_checker//resources:templates",
26+
visibility = ["//visibility:public"],
27+
)
28+
29+
exports_files([
30+
"MODULE.bazel",
31+
"BUILD",
32+
])

‎LICENSE‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright 2025 Contributors to the Eclipse Foundation
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎MODULE.bazel‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
module(
15+
name = "docs-as-code",
16+
version = "0.1.0",
17+
compatibility_level = 0,
18+
)
19+
20+
###############################################################################
21+
#
22+
# Packaging dependencies
23+
#
24+
###############################################################################
25+
bazel_dep(name = "rules_pkg", version = "1.0.1")
26+
27+
###############################################################################
28+
#
29+
# Python version
30+
#
31+
###############################################################################
32+
bazel_dep(name = "rules_python", version = "1.0.0")
33+
34+
PYTHON_VERSION = "3.12"
35+
36+
python = use_extension("@rules_python//python/extensions:python.bzl", "python")
37+
python.toolchain(
38+
configure_coverage_tool = True,
39+
is_default = True,
40+
python_version = PYTHON_VERSION,
41+
)
42+
use_repo(python)
43+
44+
###############################################################################
45+
#
46+
# docs dependencies (Sphinx)
47+
#
48+
###############################################################################
49+
pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
50+
pip.parse(
51+
hub_name = "pip_process",
52+
python_version = PYTHON_VERSION,
53+
requirements_lock = "//src:requirements.txt",
54+
)
55+
use_repo(pip, "pip_process")
56+
57+
# Additional Python rules provided by aspect, e.g. an improved version of
58+
bazel_dep(name = "aspect_rules_py", version = "1.0.0")
59+
bazel_dep(name = "buildifier_prebuilt", version = "7.3.1")
60+
61+
###############################################################################
62+
#
63+
# Generic linting and formatting rules
64+
#
65+
###############################################################################
66+
bazel_dep(name = "aspect_rules_lint", version = "1.3.1")
67+
68+
# PlantUML for docs
69+
bazel_dep(name = "rules_java", version = "8.6.3")
70+
71+
http_jar = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar")
72+
73+
http_jar(
74+
name = "plantuml",
75+
sha256 = "6f38f70455d08438979451c2257cd5d58647c6460094bb829bc2a12878d47331",
76+
url = "https://github.com/plantuml/plantuml/releases/download/v1.2025.0/plantuml-1.2025.0.jar",
77+
)
78+
79+
# Bazel LSP
80+
http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
81+
82+
http_file(
83+
name = "starpls_prebuilt",
84+
sha256 = "45692ecb9d94a19a15b1e7b240acdff5702f78cd22188dac41e1879cb8bdcdcf",
85+
urls = ["https://github.com/withered-magic/starpls/releases/download/v0.1.21/starpls-linux-amd64"],
86+
)
87+
88+
# Provides, pytest & venv
89+
bazel_dep(name = "score_python_basics", version = "0.3.0")
90+
91+
# Checker rule for CopyRight checks/fixes
92+
bazel_dep(name = "score_cr_checker", version = "0.2.0", dev_dependency = True)
93+
94+
# Grab dash
95+
bazel_dep(name = "score_dash_license_checker", version = "0.1.1", dev_dependency = True)

src/docs.bzl renamed to docs.bzl

Lines changed: 56 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# *******************************************************************************
2-
# Copyright (c) 2024 Contributors to the Eclipse Foundation
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
33
#
44
# See the NOTICE file(s) distributed with this work for additional
55
# information regarding copyright ownership.
@@ -37,22 +37,19 @@
3737
#
3838
# For user-facing documentation, refer to `/README.md`.
3939

40-
load("@aspect_rules_py//py:defs.bzl", "py_binary", "py_library", "py_venv")
41-
load("@pip_sphinx//:requirements.bzl", "all_requirements", "requirement")
42-
load("@rules_java//java:defs.bzl", "java_binary")
43-
load("@rules_pkg//pkg:mappings.bzl", "pkg_files")
44-
load("@rules_pkg//pkg:tar.bzl", "pkg_tar")
45-
load("@rules_python//python:pip.bzl", "compile_pip_requirements")
40+
load("@aspect_rules_py//py:defs.bzl", "py_binary")
41+
load("@pip_process//:requirements.bzl", "all_requirements", "requirement")
4642
load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
47-
load("//docs:_tooling/extensions/score_source_code_linker/collect_source_files.bzl", "parse_source_files_for_needs_links")
48-
load("//tools/testing/pytest:defs.bzl", "score_py_pytest")
43+
load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
44+
load("@score_python_basics//:defs.bzl", "score_virtualenv")
45+
load("//src/extensions:score_source_code_linker/collect_source_files.bzl", "parse_source_files_for_needs_links")
4946

5047
sphinx_requirements = all_requirements + [
51-
"@rules_python//python/runfiles",
52-
":plantuml_for_python",
48+
"//src:plantuml_for_python",
49+
"//src/extensions:score_extensions",
5350
]
5451

55-
def docs(source_files_to_scan_for_needs_links = None, source_dir = "docs", conf_dir = "docs", build_dir_for_incremental = "_build"):
52+
def docs(source_files_to_scan_for_needs_links = None, source_dir = "docs", conf_dir = "docs", build_dir_for_incremental = "_build", docs_targets = []):
5653
"""
5754
Creates all targets related to documentation.
5855
By using this function, you'll get any and all updates for documentation targets in one place.
@@ -61,30 +58,42 @@ def docs(source_files_to_scan_for_needs_links = None, source_dir = "docs", conf_
6158
"""
6259

6360
# Parse source files for needs links
61+
# This needs to be created to generate a target, otherwise it won't execute as dependency for other macros
6462
parse_source_files_for_needs_links(
6563
name = "score_source_code_parser",
6664
srcs_and_deps = source_files_to_scan_for_needs_links if source_files_to_scan_for_needs_links else [],
6765
)
6866

69-
# Get the output of source_code_linker
70-
# Does not work:
71-
# rule_info = native.existing_rule(source_code_linker.name)
72-
# source_code_links = rule_info[SourceCodeLinks].file.path
73-
# Workaround:
74-
source_code_links = "score_source_code_parser.json"
75-
76-
# Run-time build of documentation, incl. incremental build support and non-IDE live preview.
77-
_incremental(":score_source_code_parser", source_code_links, source_dir = source_dir, conf_dir = conf_dir, build_dir = build_dir_for_incremental)
67+
# TODO: Explain what this does / how it works?
68+
for target in docs_targets:
69+
suffix = "_" + target["suffix"] if target["suffix"] else ""
70+
external_needs_deps = target.get("target", [])
71+
external_needs_def = target.get("external_needs_info", [])
72+
_incremental(
73+
incremental_name = "incremental" + suffix,
74+
live_name = "live_preview" + suffix,
75+
conf_dir = conf_dir,
76+
source_dir = source_dir,
77+
build_dir = build_dir_for_incremental,
78+
external_needs_deps = external_needs_deps,
79+
external_needs_def = external_needs_def,
80+
)
81+
_docs(
82+
name = "docs" + suffix,
83+
format = "html",
84+
external_needs_deps = external_needs_deps,
85+
external_needs_def = external_needs_def,
86+
)
7887

7988
# Virtual python environment for working on the documentation (esbonio).
8089
# incl. python support when working on conf.py and sphinx extensions.
8190
# creates :ide_support target for virtualenv
8291
_ide_support()
8392

84-
# creates :docs target for build time documentation
85-
_docs()
93+
# creates 'needs.json' build target
94+
_docs(name = "docs_needs", format = "needs")
8695

87-
def _incremental(source_code_linker, source_code_links, source_dir = "docs", conf_dir = "docs", build_dir = "_build", extra_dependencies = list()):
96+
def _incremental(incremental_name = "incremental", live_name = "live_preview", source_dir = "docs", conf_dir = "docs", build_dir = "_build", extra_dependencies = list(), external_needs_deps = list(), external_needs_def = None):
8897
"""
8998
A target for building docs incrementally at runtime, incl live preview.
9099
Args:
@@ -97,44 +106,47 @@ def _incremental(source_code_linker, source_code_links, source_dir = "docs", con
97106
"""
98107

99108
dependencies = sphinx_requirements + extra_dependencies
100-
101109
py_binary(
102-
name = "incremental",
103-
srcs = ["//docs:_tooling/incremental.py"],
104-
data = [source_code_linker, "//docs:docs_assets"],
110+
name = incremental_name,
111+
srcs = ["//src:incremental.py"],
105112
deps = dependencies,
113+
data = [":score_source_code_parser"] + external_needs_deps,
106114
env = {
107-
"SOURCE_CODE_LINKS": source_code_links,
108115
"SOURCE_DIRECTORY": source_dir,
109116
"CONF_DIRECTORY": conf_dir,
110117
"BUILD_DIRECTORY": build_dir,
118+
"EXTERNAL_NEEDS_INFO": json.encode(external_needs_def),
111119
"ACTION": "incremental",
112120
},
113121
)
114122

115123
py_binary(
116-
name = "live_preview",
117-
srcs = ["//docs:_tooling/incremental.py"],
118-
data = ["//docs:docs_assets"],
124+
name = live_name,
125+
srcs = ["//src:incremental.py"],
119126
deps = dependencies,
127+
data = external_needs_deps,
120128
env = {
121129
"SOURCE_DIRECTORY": source_dir,
122130
"CONF_DIRECTORY": conf_dir,
123131
"BUILD_DIRECTORY": build_dir,
132+
"EXTERNAL_NEEDS_INFO": json.encode(external_needs_def),
124133
"ACTION": "live_preview",
125134
},
126135
)
127136

128137
def _ide_support():
129-
py_venv(
138+
score_virtualenv(
130139
name = "ide_support",
131140
venv_name = ".venv_docs",
132-
deps = sphinx_requirements,
141+
reqs = sphinx_requirements,
133142
)
134143

135-
def _docs():
144+
def _docs(name = "docs", format = "html", external_needs_deps = list(), external_needs_def = dict()):
145+
ext_needs_arg = "--define=external_needs_source=" + json.encode(external_needs_def)
146+
147+
#fail(ext_needs_arg)
136148
sphinx_docs(
137-
name = "docs",
149+
name = name,
138150
srcs = native.glob([
139151
"**/*.png",
140152
"**/*.svg",
@@ -143,29 +155,28 @@ def _docs():
143155
"**/*.css",
144156
"**/*.puml",
145157
"**/*.need",
146-
# Include the docs tooling itself
158+
# Include the docs src itself
147159
# Note: we don't use py_library here to make it as close as possible to docs:incremental.
148160
"**/*.py",
149161
"**/*.yaml",
150162
"**/*.json",
151163
"**/*.csv",
152-
], exclude = ["**/tests/rst/**/*.rst"]),
164+
], exclude = ["**/tests/*"]),
153165
config = ":conf.py",
154166
extra_opts = [
155167
"-W",
156168
"--keep-going",
157-
# This is 'overwriting' the configuration parameter inside sphinx. As we only get this information during runtime
158-
"--define=source_code_linker_file=$(location :score_source_code_parser)",
159-
],
169+
] + [ext_needs_arg],
160170
formats = [
161-
"html",
171+
format,
162172
],
163-
sphinx = ":sphinx_build",
173+
sphinx = "//src:sphinx_build",
164174
tags = [
165175
"manual",
166176
],
167177
tools = [
168178
":score_source_code_parser",
169-
":plantuml",
170-
],
179+
"//src:plantuml",
180+
] + external_needs_deps,
181+
visibility = ["//visibility:public"],
171182
)

0 commit comments

Comments
 (0)