✨ New config needscfg_exclude_defaults (#20)

Excludes needs configuration that are set to their default.
Useful to unclutter the output TOML file when needscfg_write_all is used.

Author: ubmarco

docs/configuration.rst

@@ -320,6 +320,59 @@ Both formats work - if a ``[needs]`` table exists, only its contents are merged.
    Use this feature to separate dynamic configuration (like version numbers or build metadata)
    from static Sphinx-Needs configuration in ``conf.py``.
 
+.. _`config_exclude_defaults`:
+
+needscfg_exclude_defaults
+-------------------------
+
+**Type:** ``bool``
+
+**Default:** ``False``
+
+Controls whether to exclude configuration options that are set to their default values.
+
+When enabled, the extension compares each Sphinx-Needs configuration value with its default
+value. If they match, the option is excluded from the output file.
+
+**Behavior:**
+
+- ``False`` (default): Include all configuration values (subject to :ref:`config_write_all` and :ref:`config_exclude_vars`)
+- ``True``: Exclude configuration values that match their default values
+
+**Use cases:**
+
+- Generate cleaner configuration files with only explicitly set values
+- Reduce noise in version-controlled configuration files
+- Make it easier to see what's been customized vs. defaults
+- Minimize file size for generated configuration
+
+**Examples:**
+
+.. code-block:: python
+
+   # Include all values, even defaults (default behavior)
+   needscfg_exclude_defaults = False
+
+   # Exclude values that match defaults
+   needscfg_exclude_defaults = True
+   needscfg_write_all = True  # Usually combined with write_all
+
+.. note::
+
+   This option works in combination with :ref:`config_write_all`:
+
+   - When ``needscfg_write_all = False``: Only explicitly set values are included (default behavior)
+   - When ``needscfg_write_all = True`` and ``needscfg_exclude_defaults = False``:
+     All values including defaults are  included
+   - When ``needscfg_write_all = True`` and ``needscfg_exclude_defaults = True``:
+     All values are considered but defaults are filtered out
+
+.. tip::
+
+   Enable both ``needscfg_write_all`` and ``needscfg_exclude_defaults`` to generate
+   configuration that includes all customized values while excluding unchanged defaults.
+   This provides a clean view of what's been explicitly configured.
+
 Examples
 --------
 

needs_config_writer/builder.py

@@ -228,6 +228,14 @@ def sort_for_reproducibility(obj: Any, path: str = "") -> Any:
             safe_value = get_safe_config(value, f"needs.{config_name}")
             # Only include serializable values (None means filtered out)
             if safe_value is not None:
+                # Check if we should exclude default values
+                if config.needscfg_exclude_defaults and attribute in config._options:
+                    # Get the default value from config options registry
+                    default_value = config._options[attribute].default
+                    # Compare current value with default value
+                    if value == default_value:
+                        continue
+
                 if config.needscfg_write_all:
                     need_attributes[config_name] = safe_value
                 else:

needs_config_writer/main.py

@@ -79,6 +79,13 @@ def setup(app: Sphinx):
         types=[list],
         description="List of TOML file paths to shallow-merge into the output configuration.",
     )
+    app.add_config_value(
+        "needscfg_exclude_defaults",
+        False,
+        "html",
+        types=[bool],
+        description="Whether to exclude configuration options that are set to their default values.",
+    )
 
     # env-before-read-docs is always called (even when no docs changed),
     # runs after Sphinx-Needs has injected configuration, and runs before

tests/complex_setups/project/conf.py

@@ -17,3 +17,6 @@
 
 needscfg_warn_on_diff = True
 """Be sure to update this - running Sphinx with -W will fail the CI, that's wanted."""
+
+needscfg_exclude_defaults = True
+"""Do not write default values into the generated config file."""

tests/complex_setups/project/ubproject.toml

@@ -3,78 +3,10 @@
 # Do not manually modify it - changes will be overwritten.
 
 [needs]
-allow_unsafe_filters = false
 build_json = true
-build_json_per_id = false
-build_json_per_id_path = "needs_id"
-build_needumls = ""
-builder_filter = "is_external==False"
-completion_option = "completion"
-constraints_failed_color = ""
-css = "modern.css"
-debug_filters = false
-debug_measurement = false
-default_layout = "clean"
-diagram_template = "\n{%- if is_need -%}\n<size:12>{{type_name}}</size>\\n**{{title|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id}}</size>\n{%- else -%}\n<size:12>{{type_name}} (part)</size>\\n**{{content|wordwrap(15, wrapstring='**\\\\n**')}}**\\n<size:10>{{id_parent}}.**{{id}}**</size>\n{%- endif -%}\n"
-duration_option = "duration"
-external_needs = []
-flow_engine = "plantuml"
-flow_link_types = [
-    "links",
-]
-flow_show_links = false
-functions = []
-id_from_title = false
-id_length = 5
 id_regex = "^[A-Z0-9_]{3,}"
 id_required = true
-include_needs = true
-json_exclude_fields = [
-    "collapse",
-    "hide",
-    "id_complete",
-    "id_parent",
-    "is_need",
-    "is_part",
-    "lineno_content",
-    "type_color",
-    "type_prefix",
-    "type_style",
-]
-json_remove_defaults = false
-max_title_length = -1
-needextend_strict = false
-part_prefix = "→ "
-permalink_data = "needs.json"
-permalink_file = "permalink.html"
-report_dead_links = true
-report_template = ""
-reproducible_json = false
-role_need_max_title_length = 30
-role_need_template = "{title} ({id})"
 schema_debug_active = true
-schema_debug_ignore = [
-    "extra_option_success",
-    "extra_link_success",
-    "select_success",
-    "select_fail",
-    "local_success",
-    "network_local_success",
-]
-schema_debug_path = "schema_debug"
-schema_severity = "info"
-service_all_data = false
-show_link_id = true
-show_link_title = false
-show_link_type = false
-statuses = []
-table_classes = []
-table_columns = "ID;TITLE;STATUS;TYPE;OUTGOING;TAGS"
-table_style = "DATATABLES"
-tags = []
-template_folder = "needs_templates/"
-title_from_content = false
-title_optional = false
 types = [
     { color = "#888888", directive = "commit", prefix = "C_", style = "card", title = "Commit" },
     { directive = "feat", prefix = "FEAT_", title = "Feature" },
@@ -83,14 +15,6 @@ types = [
     { color = "#aaaaaa", directive = "pr", prefix = "PR_", style = "card", title = "PullRequest" },
     { directive = "req", prefix = "REQ_", title = "Requirement" },
 ]
-variant_options = []
-warnings_always_warn = false
-
-[needs.constraint_failed_options]
-
-[needs.constraints]
-
-[needs.extensions]
 
 [[needs.extra_links]]
 color = "#000000"
@@ -137,8 +61,6 @@ maximum = 5
 minimum = 1
 type = "integer"
 
-[needs.filter_data]
-
 [needs.flow_configs]
 cplant = "\n    ' CPLANT by AOKI (https://github.com/aoki/cplant)\n    !define BLACK   #363D5D\n    !define RED     #F6363F\n    !define PINK    #F6216E\n    !define MAGENTA #A54FBD\n    !define GREEN   #37A77C\n    !define YELLOW  #F97A00\n    !define BLUE    #1E98F2\n    !define CYAN    #25AFCA\n    !define WHITE   #FEF2DC\n\n    ' Base Setting\n    skinparam Shadowing false\n    skinparam BackgroundColor transparent\n    skinparam ComponentStyle uml2\n    skinparam Default {\n      FontName  'Hiragino Sans'\n      FontColor BLACK\n      FontSize  10\n      FontStyle plain\n    }\n\n    skinparam Sequence {\n      ArrowThickness 1\n      ArrowColor RED\n      ActorBorderThickness 1\n      LifeLineBorderColor GREEN\n      ParticipantBorderThickness 0\n    }\n    skinparam Participant {\n      BackgroundColor BLACK\n      BorderColor BLACK\n      FontColor #FFFFFF\n    }\n\n    skinparam Actor {\n      BackgroundColor BLACK\n      BorderColor BLACK\n    }\n    "
 handwritten = "\n        skinparam handwritten true\n    "
@@ -149,8 +71,6 @@ tne = "\n    ' Based on \"Tomorrow night eighties\" color theme (see https://git
 toptobottom = "\n        top to bottom direction\n    "
 transparent = "\n    skinparam backgroundcolor transparent\n    "
 
-[needs.global_options]
-
 [needs.graphviz_styles.default.edge]
 minlen = "2"
 
@@ -359,8 +279,6 @@ meta = [
     "<<meta_links_all()>>",
 ]
 
-[needs.render_context]
-
 [needs.schema_definitions."$defs".safe-need]
 required = [
     "asil",
@@ -405,11 +323,3 @@ enum = [
     "D",
 ]
 type = "string"
-
-[needs.services]
-
-[needs.string_links]
-
-[needs.variants]
-
-[needs.warnings]

tests/test_basic.py

@@ -1207,3 +1207,66 @@ def test_merge_toml_missing_file_warning(
     assert path_ubproject.exists()
 
     app.cleanup()
+
+
+def test_exclude_defaults(tmpdir, make_app, write_fixture_files, snapshot):
+    """
+    Test that needscfg_exclude_defaults excludes options set to their default values.
+    """
+    conf_py = textwrap.dedent(
+        """
+        extensions = ["sphinx_needs", "needs_config_writer"]
+
+        # Enable writing all options
+        needscfg_write_all = True
+
+        # Enable excluding defaults
+        needscfg_exclude_defaults = True
+
+        # Customize only one option - leave others at defaults
+        needs_types = [
+            {"directive": "story", "title": "User Story", "prefix": "ST_", "color": "#BFD8D2"},
+            {"directive": "spec", "title": "Specification", "prefix": "SP_", "color": "#FEDCD2"},
+        ]
+        # set explicitly to default value
+        needs_id_regex = "^[A-Z0-9_]{5,}"
+        """
+    )
+    index_rst = textwrap.dedent(
+        """
+        Test Exclude Defaults
+        =====================
+
+        .. story:: My Story
+           :id: STORY_001
+           :tags: test
+        """
+    )
+    file_contents: dict[str, str] = {
+        "conf": conf_py,
+        "rst": index_rst,
+    }
+    write_fixture_files(tmpdir, file_contents)
+
+    app: SphinxTestApp = make_app(srcdir=Path(tmpdir), freshenv=True)
+    app.build()
+
+    assert app.statuscode == 0
+
+    path_ubproject = Path(app.builder.outdir, "ubproject.toml")
+    assert path_ubproject.exists()
+
+    content = path_ubproject.read_text()
+
+    # The customized option should be present
+    assert 'directive = "story"' in content
+    assert 'title = "Specification"' in content
+
+    # Default values should NOT be present when needscfg_exclude_defaults is True
+    # Check for some common Sphinx-Needs options that have defaults
+    # These would normally be included with needscfg_write_all=True
+    assert "statuses" not in content  # Has default value
+    assert "tags" not in content  # Has default value (empty list)
+    assert "id_regex" not in content  # Has default value (regex pattern)
+
+    app.cleanup()