Upgrade to 1.0.0 (#187)

Major Changes to how docs-as-code is used



Co-authored-by: Maximilian Sören Pollak <[email protected]>

Author: AlexanderLanin

.devcontainer/devcontainer.json

@@ -2,5 +2,5 @@
     "name": "eclipse-s-core",
     "image": "ghcr.io/eclipse-score/devcontainer:latest",
     "initializeCommand": "mkdir -p ${localEnv:HOME}/.cache/bazel",
-    "updateContentCommand": "bazel run //docs:ide_support"
+    "updateContentCommand": "bazel run //:ide_support"
 }

.github/workflows/consumer_test.yml

@@ -61,7 +61,7 @@ jobs:
       - name: Run Consumer tests
         id: consumer_tests
         run: |
-          bazel run //docs:ide_support
+          bazel run //:ide_support
           .venv_docs/bin/python -m pytest -s -v src/tests/
         env:
           FORCE_COLOR: "1"

.github/workflows/docs.yml

@@ -38,5 +38,5 @@ jobs:
       id-token: write
 
     with:
-      bazel-target: "//docs:incremental_release -- --github_user=${{ github.repository_owner }} --github_repo=${{ github.event.repository.name }}"
+      bazel-target: "//:docs -- --github_user=${{ github.repository_owner }} --github_repo=${{ github.event.repository.name }}"
       retention-days: 3

.github/workflows/format.yml

@@ -37,5 +37,5 @@ jobs:
           bazelisk-cache: true
       - name: Run formatting checks
         run: |
-          bazel run //docs:ide_support
+          bazel run //:ide_support
           bazel test //src:format.check

.github/workflows/test.yml

@@ -37,5 +37,5 @@ jobs:
           bazelisk-cache: true
       - name: Run test targets
         run: |
-          bazel run //docs:ide_support
+          bazel run //:ide_support
           bazel test //src/...

.vscode/settings.json

@@ -68,7 +68,7 @@
     "esbonio.sphinx.buildCommand": [
         "docs",
         "_build",
-        "-T", // show details in case of errors in extensions
+        "-T", // show more details in case of errors
         "--jobs",
         "auto",
         "--conf-dir",

BUILD

@@ -12,6 +12,7 @@
 # *******************************************************************************
 
 load("@score_cr_checker//:cr_checker.bzl", "copyright_checker")
+load("//:docs.bzl", "docs")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -27,7 +28,9 @@ copyright_checker(
     visibility = ["//visibility:public"],
 )
 
-exports_files([
-    "MODULE.bazel",
-    "BUILD",
-])
+docs(
+    data = [
+        "@score_process//:needs_json",
+    ],
+    source_dir = "docs",
+)

MODULE.bazel

@@ -13,8 +13,8 @@
 
 module(
     name = "score_docs_as_code",
-    version = "0.5.0",
-    compatibility_level = 0,
+    version = "1.0.0-RC1",
+    compatibility_level = 1,
 )
 
 ###############################################################################

README.md

@@ -2,44 +2,30 @@
 
 Docs-as-code tooling for Eclipse S-CORE
 
-## Overview
-
-The S-CORE docs Sphinx configuration and build code.
+Full documentation is on [GitHub Pages](https://eclipse-score.github.io/docs-as-code/).
 
 > [!NOTE]
 > This repository offers a [DevContainer](https://containers.dev/).
 > For setting this up read [eclipse-score/devcontainer/README.md#inside-the-container](https://github.com/eclipse-score/devcontainer/blob/main/README.md#inside-the-container).
 
-## Building documentation
-
-#### Run a documentation build:
-
-#### Integrate latest score main branch
-
-```bash
-bazel run //docs:incremental_latest
-```
-
-#### Access your documentation at:
-
-- `_build/` for incremental
+## Development of docs-as-code
 
-#### Getting IDE support
+### Getting IDE support for docs-as-code development
 
-Create the virtual environment via `bazel run //docs:ide_support`.\
+Create the virtual environment via `bazel run //:ide_support`.
 If your IDE does not automatically ask you to activate the newly created environment you can activate it.
 
 - In VSCode via `ctrl+p` => `Select Python Interpreter` then select `.venv_docs/bin/python`
-- In the terminal via `source .venv_docs/bin/activate`
+- In the terminal via `. .venv_docs/bin/activate`
 
-#### Format your documentation with:
+### Format your documentation with:
 
 ```bash
 bazel test //src:format.check
 bazel run //src:format.fix
 ```
 
-#### Find & fix missing copyright
+### Find & fix missing copyright
 
 ```bash
 bazel run //:copyright-check

docs.bzl

@@ -46,151 +46,72 @@ load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs
 load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
 load("@score_python_basics//:defs.bzl", "score_virtualenv")
 
-sphinx_requirements = all_requirements + [
-    "@score_docs_as_code//src:plantuml_for_python",
-    "@score_docs_as_code//src/extensions:score_plantuml",
-    "@score_docs_as_code//src/find_runfiles:find_runfiles",
-    "@score_docs_as_code//src/extensions/score_draw_uml_funcs:score_draw_uml_funcs",
-    "@score_docs_as_code//src/extensions/score_header_service:score_header_service",
-    "@score_docs_as_code//src/extensions/score_layout:score_layout",
-    "@score_docs_as_code//src/extensions/score_metamodel:score_metamodel",
-    "@score_docs_as_code//src/extensions/score_source_code_linker:score_source_code_linker",
-]
-
-def docs(source_files_to_scan_for_needs_links = None, source_dir = "docs", conf_dir = "docs", build_dir_for_incremental = "_build", docs_targets = [], deps = []):
+def docs(source_dir = "docs", data = [], deps = []):
     """
     Creates all targets related to documentation.
     By using this function, you'll get any and all updates for documentation targets in one place.
-    Current restrictions:
-    * only callable from 'docs/BUILD'
     """
 
-    # We are iterating over all provided 'targets' in order to allow for automatic generation of them without
-    # needing to modify the underlying 'docs.bzl' file.
-    for target in docs_targets:
-        suffix = "_" + target["suffix"] if target["suffix"] else ""
-        external_needs_deps = target.get("target", [])
-        external_needs_def = target.get("external_needs_info", [])
-
-        sphinx_build_binary(
-            name = "sphinx_build" + suffix,
-            visibility = ["//visibility:public"],
-            data = ["@score_docs_as_code//src:docs_assets", "@score_docs_as_code//src:docs_as_code_py_modules"] + external_needs_deps,
-            deps = sphinx_requirements + deps,
-        )
-        _incremental(
-            incremental_name = "incremental" + suffix,
-            live_name = "live_preview" + suffix,
-            conf_dir = conf_dir,
-            source_dir = source_dir,
-            build_dir = build_dir_for_incremental,
-            external_needs_deps = external_needs_deps,
-            external_needs_def = external_needs_def,
-            extra_dependencies = deps,
-        )
-        _docs(
-            name = "docs" + suffix,
-            suffix = suffix,
-            format = "html",
-            external_needs_deps = external_needs_deps,
-            external_needs_def = external_needs_def,
-        )
-        _docs(
-            name = "docs_needs" + suffix,
-            suffix = suffix,
-            format = "needs",
-            external_needs_deps = external_needs_deps,
-            external_needs_def = external_needs_def,
-        )
-
-    # Virtual python environment for working on the documentation (esbonio).
-    # incl. python support when working on conf.py and sphinx extensions.
-    # creates :ide_support target for virtualenv
-    _ide_support(deps)
-
-    # creates 'needs.json' build target
-
-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):
-    """
-    A target for building docs incrementally at runtime, incl live preview.
-    Args:
-        source_code_linker: The source code linker target to be used for linking source code to documentation.
-        source_code_links: The output from the source code linker.
-        source_dir: Directory containing the source files for documentation.
-        conf_dir: Directory containing the Sphinx configuration.
-        build_dir: Directory to output the built documentation.
-        extra_dependencies: Additional dependencies besides the centrally maintained "sphinx_requirements".
-    """
-
-    dependencies = sphinx_requirements + extra_dependencies + ["@rules_python//python/runfiles"]
-
-    # Create description tags for the incremental targets.
-    call_path = native.package_name()
-    incremental_tag = "cli_help=Build documentation incrementally:\nbazel run //" + call_path + ":" + incremental_name
-
-    if incremental_name == "incremental_latest":
-        incremental_tag = (
-            "cli_help=Build documentation incrementally (use current main branch of imported docs repositories " +
-            "(e.g. process_description)):\n" +
-            "bazel run //" + call_path + ":incremental_latest"
-        )
-    elif incremental_name == "incremental_release":
-        incremental_tag = (
-            "cli_help=Build documentation incrementally (use release version imported in MODULE.bazel):\n" +
-            "bazel run //" + call_path + ":incremental_release"
-        )
+    data = data + ["@score_docs_as_code//src:docs_assets"]
+
+    deps = deps + all_requirements + [
+        "@score_docs_as_code//src:plantuml_for_python",
+        "@score_docs_as_code//src/extensions:score_plantuml",
+        "@score_docs_as_code//src/find_runfiles:find_runfiles",
+        "@score_docs_as_code//src/extensions/score_draw_uml_funcs:score_draw_uml_funcs",
+        "@score_docs_as_code//src/extensions/score_header_service:score_header_service",
+        "@score_docs_as_code//src/extensions/score_layout:score_layout",
+        "@score_docs_as_code//src/extensions/score_metamodel:score_metamodel",
+        "@score_docs_as_code//src/extensions/score_source_code_linker:score_source_code_linker",
+    ]
+
+    sphinx_build_binary(
+        name = "sphinx_build",
+        visibility = ["//visibility:private"],
+        data = data,
+        deps = deps,
+    )
 
     py_binary(
-        name = incremental_name,
+        name = "docs",
+        tags = ["cli_help=Build documentation [run]"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        deps = dependencies,
-        # TODO: Figure out if we need all dependencies as data here or not.
-        data = ["@score_docs_as_code//src:plantuml", "@score_docs_as_code//src:docs_assets"] + dependencies + external_needs_deps,
+        data = data,
+        deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
-            "CONF_DIRECTORY": conf_dir,
-            "BUILD_DIRECTORY": build_dir,
-            "EXTERNAL_NEEDS_INFO": json.encode(external_needs_def),
+            "DATA": str(data),
             "ACTION": "incremental",
         },
-        tags = [incremental_tag],
     )
 
     py_binary(
-        name = live_name,
+        name = "live_preview",
+        tags = ["cli_help=Live preview documentation in the browser [run]"],
         srcs = ["@score_docs_as_code//src:incremental.py"],
-        deps = dependencies,
-        data = ["@score_docs_as_code//src:plantuml", "@score_docs_as_code//src:docs_assets"] + dependencies + external_needs_deps,
+        data = data,
+        deps = deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
-            "CONF_DIRECTORY": conf_dir,
-            "BUILD_DIRECTORY": build_dir,
-            "EXTERNAL_NEEDS_INFO": json.encode(external_needs_def),
+            "DATA": str(data),
             "ACTION": "live_preview",
         },
     )
 
-def _ide_support(extra_dependencies):
-    call_path = native.package_name()
     score_virtualenv(
         name = "ide_support",
+        tags = ["cli_help=Create virtual environment (.venv_docs) for documentation support [run]"],
         venv_name = ".venv_docs",
-        reqs = sphinx_requirements + extra_dependencies,
-        tags = [
-            "cli_help=Create virtual environment for documentation:\n" +
-            "bazel run //" + call_path + ":ide_support",
-        ],
+        reqs = deps,
+        # Add dependencies to ide_support, so esbonio has access to them.
+        data = data,
     )
 
-def _docs(name = "docs", suffix = "", format = "html", external_needs_deps = list(), external_needs_def = list()):
-    ext_needs_arg = "--define=external_needs_source=" + json.encode(external_needs_def)
-
-    # Clean suffix used in all generated target names
-    target_suffix = "" if name == "docs" else "_" + name[len("docs"):]
-
+    # creates 'needs.json' build target
     sphinx_docs(
-        name = name,
+        name = "needs_json",
         srcs = native.glob([
+            # TODO: we do not need images etc to generate the json file.
             "**/*.png",
             "**/*.svg",
             "**/*.md",
@@ -206,43 +127,16 @@ def _docs(name = "docs", suffix = "", format = "html", external_needs_deps = lis
             "**/*.csv",
             "**/*.inc",
         ], exclude = ["**/tests/*"], allow_empty = True),
-        config = ":conf.py",
+        config = ":" + source_dir + "/conf.py",
         extra_opts = [
             "-W",
             "--keep-going",
-        ] + [ext_needs_arg],
-        formats = [
-            format,
+            "-T",  # show more details in case of errors
+            "--jobs",
+            "auto",
+            "--define=external_needs_source=" + str(data),
         ],
-        sphinx = ":sphinx_build" + suffix,
-        tags = [
-            "manual",
-        ],
-        tools = [
-            "@score_docs_as_code//src:plantuml",
-            "@score_docs_as_code//src:docs_assets",
-        ] + external_needs_deps,
-        visibility = ["//visibility:public"],
-    )
-
-    native.filegroup(
-        name = "assets" + target_suffix,
-        srcs = native.glob(["_assets/**"], allow_empty = True),
-        visibility = ["//visibility:public"],
-    )
-
-    native.filegroup(
-        name = "html" + target_suffix,
-        srcs = [":" + name],
-        visibility = ["//visibility:public"],
-    )
-
-    pkg_files(
-        name = "html_files" + target_suffix,
-        srcs = [":html" + target_suffix],
-    )
-
-    pkg_tar(
-        name = "github_pages" + target_suffix,
-        srcs = [":html_files" + target_suffix],
+        formats = ["needs"],
+        sphinx = ":sphinx_build",
+        tools = data,
     )