docs: Added tests to packaging

Added integration tests to the packaging.
Added docstrings to functions inside the extension.
Formatting also done.

Author: MaximilianSoerenPollak

docs/BUILD

@@ -46,7 +46,6 @@ 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.
@@ -65,24 +64,24 @@ sphinx_docs(
     config = ":conf.py",
     extra_opts = [
         "--keep-going",
-        "-Dfilter_tags_file_path=$(location :filter_tags)" 
+        "-Dfilter_tags_file_path=$(location :filter_tags)",
     ],
     formats = [
         "html",
     ],
     sphinx = ":sphinx_build",
-    tools = [":filter_tags"],
     tags = [
         "manual",
     ],
+    tools = [":filter_tags"],
 )
 
 sphinx_build_binary(
     name = "sphinx_build",
     deps = sphinx_requirements + [
         ":extensions",
         "//docs/_tooling/sphinx_extensions",
-        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity"
+        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity",
     ],
 )
 
@@ -135,7 +134,7 @@ py_binary(
     deps = sphinx_requirements + [
         ":extensions",
         "//docs/_tooling/sphinx_extensions",
-        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity"
+        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity",
     ],
 )
 

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

@@ -1,14 +1,35 @@
 from pprint import pprint
+from sphinx.application import Sphinx
 from sphinx_needs.data import SphinxNeedsData, NeedsInfoType
 from sphinx_needs.config import NeedsSphinxConfig
+from sphinx.environment import BuildEnvironment
 from sphinx.util import logging
 from copy import deepcopy
 import os
 import json
 
 logger = logging.getLogger(__name__)
 
-def read_filter_tags(app):
+
+def read_filter_tags(app: Sphinx):
+    """
+    Helper function to read in the 'filter_tags' provided by `feature_flag.bzl`.
+
+    Args:
+        app: The current running Sphinx-Build application
+
+    Returns:
+       - List of tags e.g. ['some-ip','another-tag']
+       OR
+       - Empty list if there is an exception when reading the file.
+
+    Errors:
+        If 'filter_tags_file_path' can't be found in the config
+    """
+    # asserting our worldview
+    assert hasattr(
+        app.config, "filter_tags_file_path"
+    ), "Config missing filter_tags_file_path, this is mandatory."
     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:
@@ -20,50 +41,47 @@ def read_filter_tags(app):
         print(f"Could not read filter tags. Error: {e}")
         return []
 
-def set_hide(app, env):
+
+def hide_needs(app: Sphinx, env: BuildEnvironment):
+    """
+    Function that hides needs (requirements) if *all* of their tags are in the specified tags to hide.
+    Also deletes any references to hidden requirements, e.g. in 'satisfies' option.
+
+    Args:
+        app: The current running Sphinx-Build application, this will be supplied automatically
+        env: The current running BuildEnvironment, this will be supplied automatically
+    """
     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]
+    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']):
+        if need["tags"] and all(tag in filter_tags for tag in need["tags"]):
             rm_needs.append(need_id)
             need["hide"] = True
 
-    # Remove references 
+    # 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]
+            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
-    
+    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,
-    }
+    app.connect("env-updated", hide_needs)
 
-    
     return {
-        'version': '1.0',
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
     }
-
-

docs/_tooling/sphinx_extensions/test/build/modularity/BUILD

@@ -0,0 +1,24 @@
+load("@pip_sphinx//:requirements.bzl", "all_requirements", "requirement")
+load("//tools/testing/pytest:defs.bzl", "score_py_pytest")
+
+score_py_pytest(
+    name = "test_modularity",
+    size = "small",
+    srcs = [
+        "test_modularity.py",
+    ],
+    args = [
+        "--basetemp /tmp/pytest",
+        "-s",
+    ],
+    imports = ["."],
+    plugins = [
+        "sphinx.testing.fixtures",
+    ],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = [
+        "//docs/_tooling/sphinx_extensions/sphinx_extensions/build:modularity",
+    ],
+)

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

@@ -0,0 +1,179 @@
+import pytest
+import json
+from pathlib import Path
+from sphinx_needs.data import SphinxNeedsData
+from sphinx.testing.util import SphinxTestApp
+
+
+#                    ╭──────────────────────────────────────────────────────────────────────────────╮
+#                    │                         Integration Tests via Sphinx                         │
+#                    ╰──────────────────────────────────────────────────────────────────────────────╯
+
+
+@pytest.fixture(scope="session")
+def sphinx_base_dir(tmp_path_factory):
+    return tmp_path_factory.mktemp("sphinx")
+
+
+@pytest.fixture(scope="session")
+def sphinx_app_setup(sphinx_base_dir):
+    def _create_app(conf_content, rst_content, filter_tags=None):
+        src_dir = sphinx_base_dir / "src"
+        src_dir.mkdir(exist_ok=True)
+
+        (src_dir / "conf.py").write_text(conf_content)
+        (src_dir / "index.rst").write_text(rst_content)
+        (src_dir / "filter_tags.txt").write_text(filter_tags)
+
+        app = SphinxTestApp(
+            freshenv=True,
+            srcdir=Path(src_dir),
+            confdir=Path(src_dir),
+            outdir=sphinx_base_dir / "out",
+            buildername="html",
+            warningiserror=True,
+            confoverrides={"filter_tags_file_path": str(src_dir / "filter_tags.txt")},
+        )
+
+        return app
+
+    return _create_app
+
+
+@pytest.fixture(scope="session")
+def positive_filter_tags():
+    return "test-feat, some-ip"
+
+
+@pytest.fixture(scope="session")
+def negative_filter_tags():
+    return "tag1, tag2"
+
+
+@pytest.fixture(scope="session")
+def empty_filter_tags():
+    return ""
+
+
+@pytest.fixture(scope="session")
+def basic_conf():
+    return """ 
+extensions = [
+    "sphinx_needs",
+    "modularity",
+]
+needs_types = [
+    dict(directive="test_req", title="Testing Requirement", prefix="TREQ_", color="#BFD8D2", style="node"),
+    dict(directive="tool_req", title="Tooling Requirement", prefix="TOOL_", color="#BFD8D2", style="node"),
+]
+needs_extra_links = [
+    {
+        "option": "satisfies",
+        "incoming": "is satisfied by",
+        "outgoing": "satisfies",
+        "style_start": "-up",
+        "style_end": "->",
+    }
+]
+"""
+
+
+@pytest.fixture(scope="session")
+def basic_rst_file():
+    return """
+.. tool_req:: Test Tool Requirement
+   :id: TOOL_REQ_1
+   :tags: test-feat, feature1
+   :satisfies: TEST_REQ_1, TEST_REQ_20
+
+   Some content for the tool requirement
+
+.. test_req:: Testing Requirement 1
+   :id: TEST_REQ_1 
+   :tags: test-feat
+
+   Some content should be here
+
+.. test_req:: Testing Requirement 20
+   :id: TEST_REQ_20
+   :tags: feature1
+
+   More content, this one is different
+"""
+
+
+def test_modularity_hide_ok(
+    sphinx_app_setup, basic_conf, basic_rst_file, positive_filter_tags, sphinx_base_dir
+):
+    app = sphinx_app_setup(basic_conf, basic_rst_file, positive_filter_tags)
+    try:
+        app.build()
+        Needs_Data = SphinxNeedsData(app.env)
+        needs_data = {x["id"]: x for x in Needs_Data.get_needs_view().values()}
+        html = (app.outdir / "index.html").read_text()
+
+        assert "TOOL_REQ_1" in needs_data
+        assert "TEST_REQ_1" in needs_data
+        assert "TEST_REQ_20" in needs_data
+        assert needs_data["TOOL_REQ_1"]["hide"] == False
+        assert needs_data["TOOL_REQ_1"]["satisfies"] == ["TEST_REQ_20"]
+        assert needs_data["TEST_REQ_1"]["hide"] == True
+        assert needs_data["TEST_REQ_20"]["hide"] == False
+
+        assert "TOOL_REQ_1" in html
+        assert "TEST_REQ_20" in html
+        # making sure we do not see this in the final HTML
+        assert "TEST_REQ_1" not in html
+    finally:
+        app.cleanup()
+
+
+def test_modularity_hide_no_match(
+    sphinx_app_setup, basic_conf, basic_rst_file, negative_filter_tags, sphinx_base_dir
+):
+    app = sphinx_app_setup(basic_conf, basic_rst_file, negative_filter_tags)
+    try:
+        app.build()
+        Needs_Data = SphinxNeedsData(app.env)
+        needs_data = {x["id"]: x for x in Needs_Data.get_needs_view().values()}
+        html = (app.outdir / "index.html").read_text()
+
+        assert "TOOL_REQ_1" in needs_data
+        assert "TEST_REQ_1" in needs_data
+        assert "TEST_REQ_20" in needs_data
+        assert needs_data["TEST_REQ_1"]["hide"] == False
+        assert needs_data["TEST_REQ_20"]["hide"] == False
+        assert needs_data["TOOL_REQ_1"]["hide"] == False
+        assert needs_data["TOOL_REQ_1"]["satisfies"] == ["TEST_REQ_1", "TEST_REQ_20"]
+
+        assert "TOOL_REQ_1" in html
+        assert "TEST_REQ_1" in html
+        assert "TEST_REQ_20" in html
+    finally:
+        app.cleanup()
+
+
+def test_modularity_hide_no_filters(
+    sphinx_app_setup, basic_conf, basic_rst_file, empty_filter_tags, sphinx_base_dir
+):
+    app = sphinx_app_setup(basic_conf, basic_rst_file, empty_filter_tags)
+    try:
+        app.build()
+        Needs_Data = SphinxNeedsData(app.env)
+        needs_data = {x["id"]: x for x in Needs_Data.get_needs_view().values()}
+        html = (app.outdir / "index.html").read_text()
+
+        # The outcome should be the same as when we found no matches, just making sure it doesn't error and nothing happens
+        assert "TOOL_REQ_1" in needs_data
+        assert "TEST_REQ_1" in needs_data
+        assert "TEST_REQ_20" in needs_data
+        assert needs_data["TEST_REQ_1"]["hide"] == False
+        assert needs_data["TEST_REQ_20"]["hide"] == False
+        assert needs_data["TOOL_REQ_1"]["hide"] == False
+        assert needs_data["TOOL_REQ_1"]["satisfies"] == ["TEST_REQ_1", "TEST_REQ_20"]
+
+        assert "TOOL_REQ_1" in html
+        assert "TEST_REQ_1" in html
+        assert "TEST_REQ_20" in html
+    finally:
+        app.cleanup()

docs/conf.py

@@ -34,11 +34,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = [
-    "sphinx_design",
-    "sphinx_needs",
-    "modularity"
-]
+extensions = ["sphinx_design", "sphinx_needs", "modularity"]
 
 exclude_patterns = [
     "Thumbs.db",