julee 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

julee/docs/sphinx_hcd/apps.py

@@ -10,13 +10,12 @@ Provides directives:
 """
 
 import yaml
-from pathlib import Path
 from docutils import nodes
-from sphinx.util.docutils import SphinxDirective
 from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
 
 from .config import get_config
-from .utils import normalize_name, slugify, path_to_root
+from .utils import normalize_name, path_to_root, slugify
 
 logger = logging.getLogger(__name__)
 
@@ -31,7 +30,7 @@ def get_app_registry() -> dict:
 
 def get_documented_apps(env) -> set:
     """Get documented apps set from env, creating if needed."""
-    if not hasattr(env, 'documented_apps'):
+    if not hasattr(env, "documented_apps"):
         env.documented_apps = set()
     return env.documented_apps
 
@@ -42,11 +41,12 @@ def scan_app_manifests(app):
     _app_registry = {}
 
     config = get_config()
-    project_root = config.project_root
-    apps_dir = config.get_path('app_manifests')
+    apps_dir = config.get_path("app_manifests")
 
     if not apps_dir.exists():
-        logger.info(f"apps/ directory not found at {apps_dir} - no app manifests to index")
+        logger.info(
+            f"apps/ directory not found at {apps_dir} - no app manifests to index"
+        )
         return
 
     # Scan for app.yaml files
@@ -68,13 +68,13 @@ def scan_app_manifests(app):
             continue
 
         _app_registry[app_slug] = {
-            'slug': app_slug,
-            'name': manifest.get('name', app_slug.replace('-', ' ').title()),
-            'type': manifest.get('type', 'unknown'),
-            'status': manifest.get('status'),
-            'description': manifest.get('description', '').strip(),
-            'accelerators': manifest.get('accelerators', []),
-            'manifest_path': str(manifest_path),
+            "slug": app_slug,
+            "name": manifest.get("name", app_slug.replace("-", " ").title()),
+            "type": manifest.get("type", "unknown"),
+            "status": manifest.get("status"),
+            "description": manifest.get("description", "").strip(),
+            "accelerators": manifest.get("accelerators", []),
+            "manifest_path": str(manifest_path),
         }
 
     logger.info(f"Indexed {len(_app_registry)} apps from manifests")
@@ -118,47 +118,51 @@ def get_personas_for_app(app_slug: str, story_registry: list) -> list[str]:
     personas = set()
     app_normalized = normalize_name(app_slug)
     for story in story_registry:
-        if story['app_normalized'] == app_normalized:
-            personas.add(story['persona'])
+        if story["app_normalized"] == app_normalized:
+            personas.add(story["persona"])
     return sorted(personas)
 
 
-def get_journeys_for_app(app_slug: str, story_registry: list, journey_registry: dict) -> list[str]:
+def get_journeys_for_app(
+    app_slug: str, story_registry: list, journey_registry: dict
+) -> list[str]:
     """Get journeys that include stories from this app."""
     # Get story titles for this app
     app_normalized = normalize_name(app_slug)
     app_story_titles = {
-        normalize_name(s['feature'])
+        normalize_name(s["feature"])
         for s in story_registry
-        if s['app_normalized'] == app_normalized
+        if s["app_normalized"] == app_normalized
     }
 
     # Find journeys that reference these stories
     journeys = []
     for slug, journey in journey_registry.items():
-        for step in journey.get('steps', []):
-            if step.get('type') == 'story':
-                if normalize_name(step['ref']) in app_story_titles:
+        for step in journey.get("steps", []):
+            if step.get("type") == "story":
+                if normalize_name(step["ref"]) in app_story_titles:
                     journeys.append(slug)
                     break
 
     return sorted(set(journeys))
 
 
-def get_epics_for_app(app_slug: str, story_registry: list, epic_registry: dict) -> list[str]:
+def get_epics_for_app(
+    app_slug: str, story_registry: list, epic_registry: dict
+) -> list[str]:
     """Get epics that include stories from this app."""
     # Get story titles for this app
     app_normalized = normalize_name(app_slug)
     app_story_titles = {
-        normalize_name(s['feature'])
+        normalize_name(s["feature"])
         for s in story_registry
-        if s['app_normalized'] == app_normalized
+        if s["app_normalized"] == app_normalized
     }
 
     # Find epics that reference these stories
     epics = []
     for slug, epic in epic_registry.items():
-        for story_title in epic.get('stories', []):
+        for story_title in epic.get("stories", []):
             if normalize_name(story_title) in app_story_titles:
                 epics.append(slug)
                 break
@@ -184,12 +188,13 @@ class DefineAppDirective(SphinxDirective):
 
         # Return placeholder - actual rendering in doctree-resolved
         node = DefineAppPlaceholder()
-        node['app_slug'] = app_slug
+        node["app_slug"] = app_slug
         return [node]
 
 
 class DefineAppPlaceholder(nodes.General, nodes.Element):
     """Placeholder node for define-app, replaced at doctree-resolved."""
+
     pass
 
 
@@ -208,6 +213,7 @@ class AppIndexDirective(SphinxDirective):
 
 class AppIndexPlaceholder(nodes.General, nodes.Element):
     """Placeholder node for app-index, replaced at doctree-resolved."""
+
     pass
 
 
@@ -224,17 +230,24 @@ class AppsForPersonaDirective(SphinxDirective):
 
     def run(self):
         node = AppsForPersonaPlaceholder()
-        node['persona'] = self.arguments[0]
+        node["persona"] = self.arguments[0]
         return [node]
 
 
 class AppsForPersonaPlaceholder(nodes.General, nodes.Element):
     """Placeholder node for apps-for-persona, replaced at doctree-resolved."""
+
     pass
 
 
-def build_app_content(app_slug: str, docname: str, story_registry: list,
-                      journey_registry: dict, epic_registry: dict, known_personas: set):
+def build_app_content(
+    app_slug: str,
+    docname: str,
+    story_registry: list,
+    journey_registry: dict,
+    epic_registry: dict,
+    known_personas: set,
+):
     """Build the content nodes for an app."""
     from sphinx.addnodes import seealso
 
@@ -251,13 +264,15 @@ def build_app_content(app_slug: str, docname: str, story_registry: list,
     prefix = path_to_root(docname)
 
     # Description first
-    if app_data['description']:
+    if app_data["description"]:
         desc_para = nodes.paragraph()
-        desc_para += nodes.Text(app_data['description'])
+        desc_para += nodes.Text(app_data["description"])
         result_nodes.append(desc_para)
 
     # Stories count and link
-    app_stories = [s for s in story_registry if s['app_normalized'] == normalize_name(app_slug)]
+    app_stories = [
+        s for s in story_registry if s["app_normalized"] == normalize_name(app_slug)
+    ]
 
     if app_stories:
         story_count = len(app_stories)
@@ -275,20 +290,20 @@ def build_app_content(app_slug: str, docname: str, story_registry: list,
 
     # Type
     type_labels = {
-        'staff': 'Staff Application',
-        'external': 'External Application',
-        'member-tool': 'Member Tool',
+        "staff": "Staff Application",
+        "external": "External Application",
+        "member-tool": "Member Tool",
     }
     type_para = nodes.paragraph()
     type_para += nodes.strong(text="Type: ")
-    type_para += nodes.Text(type_labels.get(app_data['type'], app_data['type']))
+    type_para += nodes.Text(type_labels.get(app_data["type"], app_data["type"]))
     seealso_node += type_para
 
     # Status (if present)
-    if app_data['status']:
+    if app_data["status"]:
         status_para = nodes.paragraph()
         status_para += nodes.strong(text="Status: ")
-        status_para += nodes.Text(app_data['status'])
+        status_para += nodes.Text(app_data["status"])
         seealso_node += status_para
 
     # Personas (derived from stories)
@@ -298,7 +313,9 @@ def build_app_content(app_slug: str, docname: str, story_registry: list,
         persona_para += nodes.strong(text="Personas: ")
         for i, persona in enumerate(personas):
             persona_slug = slugify(persona)
-            persona_path = f"{prefix}{config.get_doc_path('personas')}/{persona_slug}.html"
+            persona_path = (
+                f"{prefix}{config.get_doc_path('personas')}/{persona_slug}.html"
+            )
             persona_normalized = normalize_name(persona)
 
             if persona_normalized in known_personas:
@@ -319,7 +336,9 @@ def build_app_content(app_slug: str, docname: str, story_registry: list,
         journey_para = nodes.paragraph()
         journey_para += nodes.strong(text="Journeys: ")
         for i, journey_slug in enumerate(journeys):
-            journey_path = f"{prefix}{config.get_doc_path('journeys')}/{journey_slug}.html"
+            journey_path = (
+                f"{prefix}{config.get_doc_path('journeys')}/{journey_slug}.html"
+            )
             ref = nodes.reference("", "", refuri=journey_path)
             ref += nodes.Text(journey_slug.replace("-", " ").title())
             journey_para += ref
@@ -348,19 +367,15 @@ def build_app_content(app_slug: str, docname: str, story_registry: list,
 
 def build_app_index(docname: str, story_registry: list):
     """Build the app index grouped by type."""
-    config = get_config()
-
     if not _app_registry:
         para = nodes.paragraph()
         para += nodes.emphasis(text="No apps defined")
         return [para]
 
-    prefix = path_to_root(docname)
-
     # Group apps by type
-    by_type = {'staff': [], 'external': [], 'member-tool': []}
+    by_type = {"staff": [], "external": [], "member-tool": []}
     for slug, app_data in _app_registry.items():
-        app_type = app_data['type']
+        app_type = app_data["type"]
         if app_type in by_type:
             by_type[app_type].append((slug, app_data))
         else:
@@ -369,9 +384,9 @@ def build_app_index(docname: str, story_registry: list):
     result_nodes = []
 
     type_sections = [
-        ('staff', 'Staff Applications'),
-        ('external', 'External Applications'),
-        ('member-tool', 'Member Tools'),
+        ("staff", "Staff Applications"),
+        ("external", "External Applications"),
+        ("member-tool", "Member Tools"),
     ]
 
     for type_key, type_label in type_sections:
@@ -387,14 +402,14 @@ def build_app_index(docname: str, story_registry: list):
         # App list
         app_list = nodes.bullet_list()
 
-        for slug, app_data in sorted(apps, key=lambda x: x[1]['name']):
+        for slug, app_data in sorted(apps, key=lambda x: x[1]["name"]):
             item = nodes.list_item()
             para = nodes.paragraph()
 
             # Link to app
             app_path = f"{slug}.html"
             ref = nodes.reference("", "", refuri=app_path)
-            ref += nodes.Text(app_data['name'])
+            ref += nodes.Text(app_data["name"])
             para += ref
 
             # Personas
@@ -432,13 +447,13 @@ def build_apps_for_persona(docname: str, persona_arg: str, story_registry: list)
 
     bullet_list = nodes.bullet_list()
 
-    for slug, app_data in sorted(matching_apps, key=lambda x: x[1]['name']):
+    for slug, app_data in sorted(matching_apps, key=lambda x: x[1]["name"]):
         item = nodes.list_item()
         para = nodes.paragraph()
 
         app_path = f"{prefix}{config.get_doc_path('applications')}/{slug}.html"
         ref = nodes.reference("", "", refuri=app_path)
-        ref += nodes.Text(app_data['name'])
+        ref += nodes.Text(app_data["name"])
         para += ref
 
         item += para
@@ -449,7 +464,7 @@ def build_apps_for_persona(docname: str, persona_arg: str, story_registry: list)
 
 def process_app_placeholders(app, doctree, docname):
     """Replace app placeholders with rendered content."""
-    from . import stories, journeys, epics
+    from . import epics, journeys, stories
 
     env = app.env
 
@@ -460,10 +475,14 @@ def process_app_placeholders(app, doctree, docname):
 
     # Process define-app placeholders
     for node in doctree.traverse(DefineAppPlaceholder):
-        app_slug = node['app_slug']
+        app_slug = node["app_slug"]
         content = build_app_content(
-            app_slug, docname, _story_registry,
-            journey_registry, epic_registry, _known_personas
+            app_slug,
+            docname,
+            _story_registry,
+            journey_registry,
+            epic_registry,
+            _known_personas,
         )
         node.replace_self(content)
 
@@ -474,7 +493,7 @@ def process_app_placeholders(app, doctree, docname):
 
     # Process apps-for-persona placeholders
     for node in doctree.traverse(AppsForPersonaPlaceholder):
-        persona = node['persona']
+        persona = node["persona"]
         content = build_apps_for_persona(docname, persona, _story_registry)
         node.replace_self(content)
 

julee/docs/sphinx_hcd/config.py

@@ -8,25 +8,25 @@ from copy import deepcopy
 from pathlib import Path
 
 DEFAULT_CONFIG = {
-    'paths': {
+    "paths": {
         # Where to find Gherkin feature files: {app}/features/*.feature
-        'feature_files': 'tests/e2e/',
+        "feature_files": "tests/e2e/",
         # Where to find app manifests: */app.yaml
-        'app_manifests': 'apps/',
+        "app_manifests": "apps/",
         # Where to find integration manifests: */integration.yaml
-        'integration_manifests': 'src/integrations/',
+        "integration_manifests": "src/integrations/",
         # Where to find bounded context code: {slug}/ directories
-        'bounded_contexts': 'src/',
+        "bounded_contexts": "src/",
     },
-    'docs_structure': {
+    "docs_structure": {
         # RST file locations relative to docs root
-        'applications': 'applications',
-        'personas': 'users/personas',
-        'journeys': 'users/journeys',
-        'epics': 'users/epics',
-        'accelerators': 'domain/accelerators',
-        'integrations': 'integrations',
-        'stories': 'users/stories',
+        "applications": "applications",
+        "personas": "users/personas",
+        "journeys": "users/journeys",
+        "epics": "users/epics",
+        "accelerators": "domain/accelerators",
+        "integrations": "integrations",
+        "stories": "users/stories",
     },
 }
 
@@ -76,7 +76,7 @@ class HCDConfig:
         self._project_root = self._docs_dir.parent
 
         # Merge user config with defaults
-        user_config = getattr(app.config, 'sphinx_hcd', {}) or {}
+        user_config = getattr(app.config, "sphinx_hcd", {}) or {}
         self._config = _deep_merge(DEFAULT_CONFIG, user_config)
 
     @property
@@ -98,7 +98,7 @@ class HCDConfig:
         Returns:
             Absolute Path resolved relative to project root
         """
-        rel_path = self._config['paths'].get(key, '')
+        rel_path = self._config["paths"].get(key, "")
         return self._project_root / rel_path
 
     def get_doc_path(self, key: str) -> str:
@@ -110,7 +110,7 @@ class HCDConfig:
         Returns:
             Relative path string for use in doc references
         """
-        return self._config['docs_structure'].get(key, key)
+        return self._config["docs_structure"].get(key, key)
 
 
 # Module-level config instance, set by setup()