Make scenario_directive fully generic, remove project-specific knowledge

Three changes:

1. Remove hardcoded _NON_COMMAND_TAGS, _TAG_LABELS, _TAG_ORDER constants.
   The directive no longer knows anything about dfetch commands.

2. Sort appendix sections alphabetically by tag.  The previous fixed
   ordering (update, check, add, …) was dfetch-specific.

3. Expose scenario_non_command_tags as a conf.py config value (default []).
   Any tag in that list is skipped when choosing the group tag for a
   feature file. dfetch's conf.py now sets:

       scenario_non_command_tags = ["remote-svn"]

   Section titles are derived from the tag itself (title-cased, hyphens
   replaced by spaces), so no label map is needed.

https://claude.ai/code/session_01BvyikyxX9c3sDXev8HdP4f

Author: claude

doc/_ext/scenario_directive.py

@@ -5,6 +5,11 @@
 
     extensions = ["scenario_directive"]
 
+    # Tags that are NOT group keys (e.g. environment markers).
+    # The first tag on a feature file that is not in this list becomes
+    # the appendix section for that file.  Default: no exclusions.
+    scenario_non_command_tags = ["remote-svn"]
+
 Usage in .rst files:
 
     .. scenario-include:: ../features/fetch-git-repo.feature
@@ -15,9 +20,8 @@
 If ``:scenario:`` is omitted, all scenarios in the feature file are included.
 
 **PDF / LaTeX builds** automatically move scenarios to an appendix grouped by
-the behave command-tag (``@update``, ``@check``, …) that was placed on the
-feature file.  The directive's original location receives a cross-reference to
-the appendix entry instead.
+the first non-excluded behave tag found on the feature file.  The directive's
+original location receives a cross-reference to the appendix entry instead.
 
 Use the ``:inline:`` flag to keep a specific inclusion in place even when
 building a PDF:
@@ -29,58 +33,18 @@
 the document tree:
 
     .. scenario-appendix::
-
-Behave tags treated as *command tags* map to the appendix sections.  Any tag
-that appears in ``_NON_COMMAND_TAGS`` (e.g. ``remote-svn``) is ignored when
-determining the command tag.
 """
 
 import html
 import os
 import re
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, FrozenSet, List, Tuple
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import StringList
 
 
-# ---------------------------------------------------------------------------
-# Tags that are NOT command-name tags (infrastructure / skip markers).
-# ---------------------------------------------------------------------------
-_NON_COMMAND_TAGS = {"remote-svn"}
-
-# Human-readable section titles for each command tag.
-_TAG_LABELS: Dict[str, str] = {
-    "update": "``dfetch update`` scenarios",
-    "check": "``dfetch check`` scenarios",
-    "add": "``dfetch add`` scenarios",
-    "remove": "``dfetch remove`` scenarios",
-    "diff": "``dfetch diff`` scenarios",
-    "update-patch": "``dfetch update-patch`` scenarios",
-    "format-patch": "``dfetch format-patch`` scenarios",
-    "freeze": "``dfetch freeze`` scenarios",
-    "import": "``dfetch import`` scenarios",
-    "report": "``dfetch report`` scenarios",
-    "validate": "``dfetch validate`` scenarios",
-}
-
-# Canonical display order for command tags in the appendix.
-_TAG_ORDER = [
-    "update",
-    "check",
-    "add",
-    "remove",
-    "diff",
-    "update-patch",
-    "format-patch",
-    "freeze",
-    "import",
-    "report",
-    "validate",
-]
-
-
 # ---------------------------------------------------------------------------
 # Custom node types
 # ---------------------------------------------------------------------------
@@ -108,10 +72,10 @@ def _feature_tags(feature_path: str) -> List[str]:
     return tags
 
 
-def _command_tag(feature_path: str) -> str:
-    """Return the first non-infrastructure tag from the feature file, or 'other'."""
+def _group_tag(feature_path: str, non_group_tags: FrozenSet[str]) -> str:
+    """Return the first tag not in *non_group_tags*, or ``'other'``."""
     for tag in _feature_tags(feature_path):
-        if tag not in _NON_COMMAND_TAGS:
+        if tag not in non_group_tags:
             return tag
     return "other"
 
@@ -142,6 +106,11 @@ def _full_feature_content(feature_path: str) -> str:
         return fh.read()
 
 
+def _tag_section_title(tag: str) -> str:
+    """Human-readable section title derived from *tag* alone."""
+    return tag.replace("-", " ").title()
+
+
 # ---------------------------------------------------------------------------
 # scenario-include directive
 # ---------------------------------------------------------------------------
@@ -166,28 +135,28 @@ class ScenarioIncludeDirective(Directive):
     # Internal helpers
     # ------------------------------------------------------------------
 
+    def _env(self):
+        return self.state.document.settings.env
+
     def _is_pdf(self) -> bool:
-        env = self.state.document.settings.env
-        return env.app.builder.name in ("latex", "rinoh")
+        return self._env().app.builder.name in ("latex", "rinoh")
 
     def _feature_abs(self, feature_file: str) -> str:
-        env = self.state.document.settings.env
+        env = self._env()
         path = os.path.abspath(os.path.join(env.app.srcdir, feature_file))
         if not os.path.exists(path):
             raise self.error(f"Feature file not found: {path}")
         return path
 
     def _include_path(self, feature_abs: str) -> str:
         """Path for literalinclude, relative to the current RST document."""
-        env = self.state.document.settings.env
+        env = self._env()
         current_doc_dir = os.path.dirname(
             os.path.join(env.app.srcdir, env.docname)
         )
         return os.path.relpath(feature_abs, current_doc_dir)
 
-    def _requested_scenarios(
-        self, available: Tuple[str, ...]
-    ) -> List[str]:
+    def _requested_scenarios(self, available: Tuple[str, ...]) -> List[str]:
         return [
             t.strip()
             for t in self.options.get("scenario", "").splitlines()
@@ -246,10 +215,13 @@ def _render_pdf(
         feature_abs: str,
         scenario_titles: List[str],
     ) -> List[nodes.Node]:
-        env = self.state.document.settings.env
+        env = self._env()
+        non_group_tags = frozenset(
+            getattr(env.config, "scenario_non_command_tags", [])
+        )
         basename = os.path.splitext(os.path.basename(feature_abs))[0]
         label = f"appendix-{basename}"
-        tag = _command_tag(feature_abs)
+        tag = _group_tag(feature_abs, non_group_tags)
         title = _feature_title(feature_abs)
 
         # ----------------------------------------------------------
@@ -265,7 +237,7 @@ def _render_pdf(
                 "feature_file": feature_file,
                 "feature_abs": feature_abs,
                 "feature_title": title,
-                "command_tag": tag,
+                "group_tag": tag,
                 "label": label,
                 "source_doc": env.docname,
                 "scenarios": list(scenario_titles),
@@ -319,7 +291,8 @@ class ScenarioAppendixDirective(Directive):
 
     Place this directive once in the document (typically in an appendix
     page).  During the write phase it is replaced by sections grouped by
-    command tag, containing the full content of each referenced feature file.
+    the first non-excluded tag, sorted alphabetically, containing the full
+    content of each referenced feature file.
 
     In HTML builds scenarios appear inline in the main text, so this
     directive emits an explanatory note instead.
@@ -332,13 +305,12 @@ class ScenarioAppendixDirective(Directive):
     def run(self) -> List[nodes.Node]:
         env = self.state.document.settings.env
         if env.app.builder.name not in ("latex", "rinoh"):
-            # HTML: scenarios are inline; provide a brief orientation note.
             note = nodes.note()
             para = nodes.paragraph()
             para += nodes.Text(
                 "In the HTML edition, feature scenarios appear as expandable "
                 "examples directly within each guide section. "
-                "In the PDF edition they are collected here, grouped by command."
+                "In the PDF edition they are collected here, grouped by tag."
             )
             note += para
             return [note]
@@ -351,34 +323,22 @@ def run(self) -> List[nodes.Node]:
 # Event: replace placeholder with actual appendix content
 # ---------------------------------------------------------------------------
 
-def _build_appendix_nodes(
-    entries: Dict,
-) -> List[nodes.Node]:
+
+def _build_appendix_nodes(entries: Dict) -> List[nodes.Node]:
     """Build docutils section nodes for every collected appendix entry."""
-    # Group by command tag
     by_tag: Dict[str, List] = {}
     for entry in entries.values():
-        by_tag.setdefault(entry["command_tag"], []).append(entry)
-
-    # Determine display order
-    ordered_tags = sorted(
-        by_tag.keys(),
-        key=lambda t: (
-            _TAG_ORDER.index(t) if t in _TAG_ORDER else len(_TAG_ORDER),
-            t,
-        ),
-    )
+        by_tag.setdefault(entry["group_tag"], []).append(entry)
 
     result: List[nodes.Node] = []
-    for tag in ordered_tags:
+    for tag in sorted(by_tag):
         tag_entries = sorted(by_tag[tag], key=lambda e: e["feature_title"])
         label = f"appendix-{tag}"
-        section_title = _TAG_LABELS.get(tag, f"``dfetch {tag}`` scenarios")
 
         tag_section = nodes.section()
         tag_section["ids"] = [label]
         tag_section["names"] = [label]
-        tag_section += nodes.title(text=section_title)
+        tag_section += nodes.title(text=_tag_section_title(tag))
 
         for entry in tag_entries:
             feat_section = nodes.section()
@@ -445,6 +405,7 @@ def merge_scenario_appendix(app, env, docnames, other) -> None:
 
 def setup(app):
     """Register directives, nodes, and event hooks."""
+    app.add_config_value("scenario_non_command_tags", [], "env")
     app.add_directive("scenario-include", ScenarioIncludeDirective)
     app.add_directive("scenario-appendix", ScenarioAppendixDirective)
     app.add_node(scenario_appendix_placeholder)
@@ -453,7 +414,7 @@ def setup(app):
     app.connect("env-merge-info", merge_scenario_appendix)
 
     return {
-        "version": "0.2",
+        "version": "0.3",
         "parallel_read_safe": True,
         "parallel_write_safe": True,
     }

doc/appendix/scenarios.rst

@@ -6,9 +6,6 @@ Appendix: Feature scenarios
 This appendix collects all the Gherkin feature scenarios that illustrate
 dfetch's behaviour. In the HTML documentation each scenario appears inline,
 folded inside an expandable *Example* block. In the PDF edition the scenarios
-are moved here to keep the main text readable; each location in the guide
-carries a cross-reference back to the relevant section below.
-
-The sections are grouped by the dfetch command they exercise.
+are moved here, grouped alphabetically by tag.
 
 .. scenario-appendix::

doc/conf.py

@@ -61,6 +61,11 @@
 copybutton_prompt_text = r"\$ |>>> |\.\.\. "
 copybutton_prompt_is_regexp = True
 
+# scenario_directive: tags that are not group keys (environment markers, etc.)
+# The first tag on a feature file that is not in this list determines which
+# appendix section the file ends up in.
+scenario_non_command_tags = ["remote-svn"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]