docs: WIP packaging concept

This PR provdies a way to disable requirements based on feature flags
set in bazel.
It has a 'translation' layer where we can map feature flags to tags,
which are then used to disable/hide requirements.

Author: MaximilianSoerenPollak

docs/BUILD

@@ -44,6 +44,10 @@ load("@rules_pkg//pkg:tar.bzl", "pkg_tar")
 load("@rules_python//python:defs.bzl", "py_library")
 load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
+load("//tools/feature_flags:feature_flags.bzl", "define_feature_flags")
+
+
+define_feature_flags(name = "filter_tags")
 
 # all_requirements include esbonio which we don't need most of the time.
 # Hint: the names are e.g. "@@rules_python~~pip~pip_sphinx//esbonio:pkg"
@@ -61,11 +65,13 @@ sphinx_docs(
     config = ":conf.py",
     extra_opts = [
         "--keep-going",
+        "-Dfilter_tags_file_path=$(location :filter_tags)" 
     ],
     formats = [
         "html",
     ],
     sphinx = ":sphinx_build",
+    tools = [":filter_tags"],
     tags = [
         "manual",
     ],
@@ -76,6 +82,7 @@ sphinx_build_binary(
     deps = sphinx_requirements + [
         ":extensions",
         "//docs/_tooling/sphinx_extensions",
+        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity"
     ],
 )
 
@@ -124,9 +131,11 @@ pkg_tar(
 py_binary(
     name = "incremental",
     srcs = ["_tooling/incremental.py"],
+    data = [":flags_file"],
     deps = sphinx_requirements + [
         ":extensions",
         "//docs/_tooling/sphinx_extensions",
+        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity"
     ],
 )
 
@@ -138,3 +147,9 @@ py_venv(
     # Until release of esbonio 1.x, we need to install it ourselves so the VS Code extension can find it.
     deps = sphinx_requirements + [requirement("esbonio")],
 )
+
+filegroup(
+    name = "flags_file",
+    srcs = [":filter_tags"],
+    output_group = "flags_file",
+)

docs/_tooling/incremental.py

@@ -21,14 +21,15 @@
 if workspace:
     os.chdir(workspace)
 
-
+flags_file = "docs/feature_flags.txt"
 sphinx_main(
     [
         "docs",  # src dir
         "_build",  # out dir
         "--jobs",
         "auto",
         "--conf-dir",
-        "docs",
+        "docs", 
+        "-D", f"filter_tags_file_path={flags_file}"
     ]
 )

docs/_tooling/sphinx_extensions/BUILD

@@ -18,7 +18,7 @@ load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs
 py_library(
     name = "sphinx_extensions",
     srcs = glob(["sphinx_extensions/**/*.py"]),
-    imports = ["."],
+    imports = ["sphinx_extensions"],
     visibility = [
         "//visibility:public",
     ],

docs/_tooling/sphinx_extensions/sphinx_extensions/build/BUILD

@@ -0,0 +1,15 @@
+load("@pip_sphinx//:requirements.bzl", "all_requirements", "requirement")
+load("@rules_python//python:defs.bzl", "py_library")
+
+py_library(
+    name = "modularity",
+    srcs = glob(["modularity/*.py"]),
+    imports = ["modularity"],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = [
+        requirement("sphinx"),
+        requirement("sphinx-needs"),
+    ],
+)

docs/_tooling/sphinx_extensions/sphinx_extensions/build/modularity/README.md

@@ -0,0 +1,120 @@
+
+# Modularity Sphinx Extension
+
+A Sphinx extension that enables conditional documentation rendering based on feature flags.
+
+## Overview
+
+The extension consists of two main components:
+
+1. `feature_flags.bzl`: A Bazel translation layer that converts commands into tags
+2. `modularity`: A Sphinx extension that filters documentation based on feature flags
+
+It currently functions as a blacklist.  
+**The extension is setup so it only disables requirements where *all* tags are contained within the filtered ones.**  
+
+## Usage
+
+### Command Line
+
+Disable features when building documentation:
+
+```bash
+docs build //docs:docs --//docs:feature1=true
+```
+
+## Configuration
+
+### Feature Flags (feature_flags.bzl)
+
+The `feature_flags.bzl` file takes care of the following things:
+
+- Feature-to-tag translation
+- Feature name to flag mappings
+- Default values for flags
+- Temporary file generation for flag storage
+
+Example configuration:
+
+Mapping of features to tags is defined as follows:
+
+```bzl
+FEATURE_TAG_MAPPING = {
+    "feature1": ["some-ip", "tag2"], # --//docs:feature1=true -> will expand to 'some-ip', 'tag2'
+    "second-feature": ["test-feat", "tag6"],
+}
+```
+
+The default values are defined like such: 
+```bzl
+def define_feature_flags(name):
+    bool_flag(
+        name = "feature1",
+        build_setting_default = False,
+    )
+    bool_flag(
+        name = "second-feature",
+        build_setting_default = False,
+    )
+    
+    feature_flag_translator(
+        name = name,
+        flags = {":feature1": "True", ":second-feature": "True"},
+    )
+```
+As can be seen here, each flag needs to be registered as well as have a default value defined. 
+After adding new flags it's possible to call them via the `--//docs:<flag-name>=<value>` command
+
+The `feature_flag.bzl` file will after parsing the flags and translating them write a temporary file with all to be disabled tags.
+
+### Extension (modularity)
+
+The extension processes the temporary flag file and disables documentation sections tagged with disabled features.
+
+#### Use in requirements
+
+All requirements which tags are **all** contained within the tags that we look for, will be disabled.  
+Here an eaxmple to illustrate the point.  
+We will disable the `test-feat` tag via feature flags. If we take the following example rst:
+```rst
+.. tool_req::  Test_TOOL
+    :id: TEST_TOOL_REQ
+    :tags: feature1, test-feat 
+    :satisfies: TEST_STKH_REQ_1, TEST_STKH_REQ_20
+  
+    We will see that this should still be rendered but 'TEST_STKH_REQ_1' will be missing from the 'satisfies' option
+
+.. stkh_req:: Test_REQ disable
+   :id: TEST_STKH_REQ_1
+   :tags: test-feat
+   
+   This is a requirement that we would want to disable via the feature flag
+
+.. stkh_req:: Test_REQ do not disable
+   :id: TEST_STKH_REQ_20
+   :tags: feature1
+
+   This requirement will not be disabled.
+```
+We can then build it with our feature flag enabled via `bazel build //docs:docs --//docs:second-feature=true` 
+This will expand via our translation layer `feature_flag.bzl` into the tags `test-feat` and `tag5`.  
+
+**The extension is setup so it only disables requirements where *all* tags are contained within the filtered ones.**  
+In the rst above `TEST_TOOL_REQ` has the `test-feat` tag but it also has the `feature1` tag, therefore it wont be disabled.
+In contrast, TEST_STKH_REQ_20 has only the `test-feat` tag, therefore it will be disabled and removed from any links as well.
+
+If we now look at the rendered HTML:
+![](rendered_html.png)
+
+We can confirm that the `TEST_STKH_REQ_1` requirement is gone and so is the reference to it from `TEST_TOOL_REQ`. 
+
+
+*However, keep in mind that in the source code the actual underlying RST has not changed, it's just the HTML.*  
+This means that one can still see all the requirements there and also if searching for it will still find the document where it is mentioned. 
+
+
+### How the extension achieves this? 
+
+The extension uses a sphinx-needs buildin option called `hide`. If a need has the `hide=True` it will not be shown in the final HTML.  
+It also gatheres a list of all 'hidden' requirements as it then in a second iteration removes these from any of the possible links.
+

docs/_tooling/sphinx_extensions/sphinx_extensions/build/modularity/modularity.py

@@ -0,0 +1,69 @@
+from pprint import pprint
+from sphinx_needs.data import SphinxNeedsData, NeedsInfoType
+from sphinx_needs.config import NeedsSphinxConfig
+from sphinx.util import logging
+from copy import deepcopy
+import os
+import json
+
+logger = logging.getLogger(__name__)
+
+def read_filter_tags(app):
+    print(f"Attempting to read filter tags from: {app.config.filter_tags_file_path}")
+    try:
+        with open(app.config.filter_tags_file_path, "r") as f:
+            content = f.read().strip()
+            filter_tags = [tag.strip() for tag in content.split(",")] if content else []
+            print(f"Successfully read filter tags: {filter_tags}")
+            return filter_tags
+    except Exception as e:
+        print(f"Could not read filter tags. Error: {e}")
+        return []
+
+def set_hide(app, env):
+    filter_tags = read_filter_tags(app)
+    Need_Data = SphinxNeedsData(env)
+    needs = Need_Data.get_needs_mutable()
+    extra_links = [x['option'] for x in NeedsSphinxConfig(env.config).extra_links]
+    rm_needs_docs = set()
+    rm_needs = []
+    for need_id, need in needs.items():
+        if need['tags'] and all(tag in filter_tags for tag in need['tags']):
+            rm_needs.append(need_id)
+            need["hide"] = True
+
+    # Remove references 
+    for need_id in needs:
+        for opt in extra_links:
+            needs[need_id][opt] = [x for x in needs[need_id][opt] if x not in rm_needs]
+            needs[need_id][opt + "_back"] = [x for x in needs[need_id][opt + "_back"] if x not in rm_needs]
+
+
+def setup(app):
+    app.add_config_value('filter_tags', [], 'env', [list])
+    app.add_config_value('filter_tags_file_path', None, 'env')  # Change default from "" to None
+    
+    # Add validation
+    def validate_config(app, config):
+        if not config.filter_tags_file_path:
+            logger.warning("No filter_tags_file_path configured")
+        elif not os.path.exists(config.filter_tags_file_path):
+            logger.error(f"Filter tags file not found at: {config.filter_tags_file_path}")
+    
+    app.connect('config-inited', validate_config)
+    app.connect("env-updated", set_hide)
+    
+    return {
+        'version': '1.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+    
+    return {
+        'version': '1.0',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+

docs/_tooling/sphinx_extensions/sphinx_extensions/build/modularity/rendered_html.png

@@ -37,6 +37,7 @@
 extensions = [
     "sphinx_design",
     "sphinx_needs",
+    "modularity"
 ]
 
 exclude_patterns = [

docs/conf.py

@@ -0,0 +1 @@
+package(default_visibility = ["//visibility:public"])

tools/feature_flags/BUILD

@@ -0,0 +1,50 @@
+# tools/feature_flags/feature_flags.bzl
+load("@bazel_skylib//rules:common_settings.bzl", "bool_flag", "BuildSettingInfo")
+
+OutputPathInfo = provider(fields = ["path"])
+
+FEATURE_TAG_MAPPING = {
+    "feature1": ["some-ip", "tag2"],
+    "second-feature": ["test-feat", "tag6"],
+}
+
+def _feature_flag_translator_impl(ctx):
+    output = ctx.actions.declare_file("feature_flags.txt")
+    tags = []
+    for flag, _ in ctx.attr.flags.items():
+        if flag[BuildSettingInfo].value:
+            flag_name = flag.label.name
+            if flag_name in FEATURE_TAG_MAPPING:
+                tags.extend(FEATURE_TAG_MAPPING[flag_name])
+            else:
+                tags.append(flag_name)
+    
+    content = ",".join(tags)
+    ctx.actions.write(output = output, content = content)
+    
+    return [DefaultInfo(files = depset([output]))]
+
+feature_flag_translator = rule(
+    implementation = _feature_flag_translator_impl,
+    attrs = {
+        "flags": attr.label_keyed_string_dict(
+            mandatory = True,
+            providers = [BuildSettingInfo],
+        ),
+    },
+)
+
+def define_feature_flags(name):
+    bool_flag(
+        name = "feature1",
+        build_setting_default = False,
+    )
+    bool_flag(
+        name = "second-feature",
+        build_setting_default = False,
+    )
+    
+    feature_flag_translator(
+        name = name,
+        flags = {":feature1": "True", ":second-feature": "True"},
+    )