[Sphinx Extension] Add check for required guideline fields (#45)

* Add check for required guideline fields

* Remove debugging output

* Apply suggestions from code review

Co-authored-by: Pete LeVasseur <[email protected]>

* test: intentionally break build to verify CI failure

this commit removes tags, decidability, scope fields from types-and-traits.rst

* Revert temporary build failure for validation test

---------

Co-authored-by: Pete LeVasseur <[email protected]>

Author: x0rw

exts/coding_guidelines/__init__.py

@@ -5,6 +5,7 @@
 from . import write_guidelines_ids
 from . import std_role
 from . import fls_linking
+from . import guidelines_checks 
 
 from sphinx_needs.api import add_dynamic_function
 from sphinx.errors import SphinxError
@@ -15,7 +16,6 @@
 # Get the Sphinx logger
 logger = logging.getLogger('sphinx')
 
-
 class CodingGuidelinesDomain(Domain):
     name = "coding-guidelines"
     label = "Rust Standard Library"
@@ -52,9 +52,19 @@ def setup(app):
     app.add_config_value(name='enable_spec_lock_consistency',
                          default=True,
                          rebuild='env')
+    app.add_config_value(
+        name='required_guideline_fields',
+        default=['release', 'fls', 'decidability', 'scope'],
+        rebuild='env',
+        types=[list],
+    )
+
+    app.connect('env-check-consistency', guidelines_checks.validate_required_fields)
 
     app.connect('env-check-consistency', fls_checks.check_fls)
+
     app.connect('build-finished', write_guidelines_ids.build_finished)
+
     app.connect('build-finished', fls_linking.build_finished)
 
     return {

exts/coding_guidelines/guidelines_checks.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+from sphinx.errors import SphinxError
+from sphinx_needs.data import SphinxNeedsData
+import logging
+
+logger = logging.getLogger('sphinx')
+
+class IntegrityCheckError(SphinxError):
+    category = "Integrity Check Error"
+
+def validate_required_fields(app, env):
+    """
+    Validate the required fields defined in conf.py 
+    """
+    logger.debug("Validating required fields")
+    data = SphinxNeedsData(env)
+    needs = data.get_needs_view()
+
+    required_fields = app.config.required_guideline_fields  # Access the configured values
+
+    for key, value in needs.items():
+        if value.get('type') == 'guideline':
+            missing_fields = []
+            for field in required_fields:
+                if value.get(field) in  (None, '', []):
+                    missing_fields.append(field)
+
+            if missing_fields:
+                error_message = (
+                    f"Guideline '{value.get('title')}' (ID: {value.get('id')}) "
+                    f"in {value.get('docname')}:{value.get('lineno')} is missing the following required fields: "
+                    f"{', '.join(missing_fields)}"
+                )
+                logger.error(error_message)
+                app.builder.statuscode = 1
+                raise IntegrityCheckError(error_message) 
+            logger.info("No missing required field")

src/conf.py

@@ -127,6 +127,10 @@
 # Enable needs export
 needs_extra_options = ["category", "recommendation", "fls", "decidability", "scope", "release"]
 
+
+# Required guideline fields
+required_guideline_fields = ['category', 'release', 'fls', 'decidability', 'scope', 'tags'] # Id is automatically generated
+
 # -- Options for HTML output -------------------------------------------------
 
 # Configure the theme