Switch docstring directive prefix from @ to %

Author: rich-iannone

great_docs/_directives.py

@@ -31,18 +31,18 @@ def __bool__(self) -> bool:
         return bool(self.family or self.order is not None or self.seealso or self.nodoc)
 
 
-# Single-line directive patterns (with @ prefix)
+# Single-line directive patterns (with % prefix, no colon)
 # Each pattern matches a complete line starting with the directive
 DIRECTIVE_PATTERNS = {
-    "family": re.compile(r"^\s*@family:\s*(.+?)\s*$", re.MULTILINE),
-    "order": re.compile(r"^\s*@order:\s*(\d+)\s*$", re.MULTILINE),
-    "seealso": re.compile(r"^\s*@seealso:\s*(.+?)\s*$", re.MULTILINE),
-    "nodoc": re.compile(r"^\s*@nodoc:\s*(true|yes|1)?\s*$", re.MULTILINE | re.IGNORECASE),
+    "family": re.compile(r"^\s*%family\s+(.+?)\s*$", re.MULTILINE),
+    "order": re.compile(r"^\s*%order\s+(\d+)\s*$", re.MULTILINE),
+    "seealso": re.compile(r"^\s*%seealso\s+(.+?)\s*$", re.MULTILINE),
+    "nodoc": re.compile(r"^\s*%nodoc(?:\s+(true|yes|1))?\s*$", re.MULTILINE | re.IGNORECASE),
 }
 
 # Combined pattern for stripping all directives (matches the whole line including newline)
 ALL_DIRECTIVES_PATTERN = re.compile(
-    r"^\s*@(?:family|order|seealso|nodoc):.*$\n?", re.MULTILINE | re.IGNORECASE
+    r"^\s*%(?:family|order|seealso|nodoc)(?:\s+.*)?$\n?", re.MULTILINE | re.IGNORECASE
 )
 
 
@@ -65,9 +65,9 @@ def extract_directives(docstring: str | None) -> DocDirectives:
     >>> doc = '''
     ... Short description.
     ...
-    ... @family: Family Name
-    ... @order: 1
-    ... @seealso: func_a, func_b
+    ... %family Family Name
+    ... %order 1
+    ... %seealso func_a, func_b
     ...
     ... Parameters
     ... ----------
@@ -86,20 +86,20 @@ def extract_directives(docstring: str | None) -> DocDirectives:
     if not docstring:
         return directives
 
-    # Extract @family
+    # Extract %family
     if match := DIRECTIVE_PATTERNS["family"].search(docstring):
         directives.family = match.group(1).strip()
 
-    # Extract @order
+    # Extract %order
     if match := DIRECTIVE_PATTERNS["order"].search(docstring):
         directives.order = int(match.group(1))
 
-    # Extract @seealso (comma-separated list)
+    # Extract %seealso (comma-separated list)
     if match := DIRECTIVE_PATTERNS["seealso"].search(docstring):
         items = [item.strip() for item in match.group(1).split(",")]
         directives.seealso = [item for item in items if item]
 
-    # Extract @nodoc
+    # Extract %nodoc
     if DIRECTIVE_PATTERNS["nodoc"].search(docstring):
         directives.nodoc = True
 
@@ -122,15 +122,15 @@ def strip_directives(docstring: str | None) -> str:
     Returns
     -------
     str
-        The docstring with all @directive: lines removed.
+        The docstring with all %directive lines removed.
 
     Examples
     --------
     >>> doc = '''
     ... Short description.
     ...
-    ... @family: Family Name
-    ... @order: 1
+    ... %family Family Name
+    ... %order 1
     ...
     ... Parameters
     ... ----------
@@ -168,7 +168,7 @@ def has_directives(docstring: str | None) -> bool:
     Returns
     -------
     bool
-        True if any @directive: pattern is found.
+        True if any %directive pattern is found.
     """
     if not docstring:
         return False

great_docs/assets/post-render.py

@@ -152,29 +152,39 @@ def reformat_signature(match):
 
 def strip_directives_from_html(html_content):
     """
-    Remove Great Docs @directive: lines from rendered HTML.
+    Remove Great Docs %directive lines from rendered HTML.
 
-    Directives like @family:, @order:, @seealso:, and @nodoc: are used for
+    Directives like %family, %order, %seealso, and %nodoc are used for
     organizing documentation but should not appear in the final rendered output.
     This function removes them as a safety net after quartodoc rendering.
     """
-    # Pattern matches directive lines that may appear in HTML
-    # They could be plain text, inside <p> tags, or other HTML elements
-    # Match: optional whitespace, @directive:, value, end of line
-    directive_pattern = re.compile(
-        r"^\s*@(?:family|order|seealso|nodoc):\s*.*$\n?",
+    # Match directives wrapped in <p> tags
+    # e.g., <p>%family Something</p>
+    p_directive_pattern = re.compile(
+        r"<p>\s*%(?:family|order|seealso|nodoc)(?:\s+[^<]*)?\s*</p>\s*\n?",
+        re.IGNORECASE,
+    )
+
+    # Match standalone directive lines (plain text)
+    # e.g., %family Something
+    standalone_directive_pattern = re.compile(
+        r"^\s*%(?:family|order|seealso|nodoc)(?:\s+.*)?\s*$\n?",
         re.MULTILINE | re.IGNORECASE,
     )
 
-    # Also match directives that got wrapped in <p> tags
-    # e.g., <p>@family: Something</p>
-    p_directive_pattern = re.compile(
-        r"<p>\s*@(?:family|order|seealso|nodoc):\s*[^<]*</p>\s*\n?",
+    # Match directives that might be inline within text
+    inline_directive_pattern = re.compile(
+        r"%(?:family|order|seealso|nodoc)(?:\s+[^\n<]*)?",
         re.IGNORECASE,
     )
 
-    cleaned = directive_pattern.sub("", html_content)
-    cleaned = p_directive_pattern.sub("", cleaned)
+    # Apply patterns in order of specificity
+    cleaned = p_directive_pattern.sub("", html_content)
+    cleaned = standalone_directive_pattern.sub("", cleaned)
+    cleaned = inline_directive_pattern.sub("", cleaned)
+
+    # Clean up any resulting empty paragraphs
+    cleaned = re.sub(r"<p>\s*</p>\s*\n?", "", cleaned)
 
     return cleaned
 

great_docs/cli.py

@@ -145,13 +145,13 @@ def preview(project_path, docs_dir):
     "--verbose",
     "-v",
     is_flag=True,
-    help="Show detailed information including @seealso and @order values",
+    help="Show detailed information including %seealso and %order values",
 )
 def scan(project_path, docs_dir, verbose):
-    """Scan docstrings for @family directives and preview API organization.
+    """Scan docstrings for %family directives and preview API organization.
 
-    This command analyzes your package's docstrings to find @family, @order,
-    @seealso, and @nodoc directives, then shows how the API reference would
+    This command analyzes your package's docstrings to find %family, %order,
+    %seealso, and %nodoc directives, then shows how the API reference would
     be organized.
 
     Use this to preview your documentation structure before building.
@@ -173,11 +173,11 @@ def scan(project_path, docs_dir, verbose):
         directive_map = docs._extract_all_directives(importable_name)
 
         if not directive_map:
-            click.echo("No @family directives found in docstrings.")
+            click.echo("No %family directives found in docstrings.")
             click.echo("\nTo organize your API documentation, add directives to your docstrings:")
-            click.echo("    @family: Family Name")
-            click.echo("    @order: 1")
-            click.echo("    @seealso: other_func, AnotherClass")
+            click.echo("    %family Family Name")
+            click.echo("    %order 1")
+            click.echo("    %seealso other_func, AnotherClass")
             sys.exit(0)
 
         # Group by family
@@ -216,16 +216,16 @@ def scan(project_path, docs_dir, verbose):
 
                 click.echo(f"\n  {family_name} ({len(items)} item(s)):")
                 for item in items:
-                    order_str = f" [@order: {item['order']}]" if item["order"] is not None else ""
+                    order_str = f" [%order {item['order']}]" if item["order"] is not None else ""
                     click.echo(f"    • {item['name']}{order_str}")
 
                     if verbose and item["seealso"]:
                         seealso_str = ", ".join(item["seealso"])
-                        click.echo(f"      └─ @seealso: {seealso_str}")
+                        click.echo(f"      └─ %seealso {seealso_str}")
 
         # Show nodoc items
         if nodoc_items:
-            click.echo(f"\n🚫 Excluded (@nodoc): {len(nodoc_items)} item(s)")
+            click.echo(f"\n🚫 Excluded (%nodoc): {len(nodoc_items)} item(s)")
             if verbose:
                 for item in sorted(nodoc_items):
                     click.echo(f"    • {item}")