fix: separate author name into given and surname to suppress mystmd warning

Author: softwareentrepreneer

src/afterpython/cli/commands/sync.py

@@ -6,7 +6,11 @@
 from tomlkit.toml_document import TOMLDocument
 
 import afterpython as ap
-from afterpython.utils import convert_author_name_to_id, normalize_static_path
+from afterpython.utils import (
+    build_author_name,
+    convert_author_name_to_id,
+    normalize_static_path,
+)
 
 
 def _myst_favicon_path(path: str) -> str:
@@ -23,20 +27,21 @@ def _sync_authors_yml(authors: list[tuple[str, str | None]]):
 
     # read myst.yml from docs path to get "version"
     doc_myst_yml = read_yaml(ap.paths.afterpython_path / "doc" / "myst.yml")
+    entries = []
+    for author in authors:
+        # author is a tuple of (name, email)
+        name = str(author[0]).strip()
+        entries.append(
+            {
+                "id": convert_author_name_to_id(name),
+                "name": build_author_name(name),
+                "email": str(author[1]),
+                # "github": ...
+            }
+        )
     data = {
         "version": doc_myst_yml["version"],
-        "project": {
-            "contributors": [
-                # NOTE: author is a tuple of (name, email), so author[0] is the name and author[1] is the email
-                {
-                    "id": convert_author_name_to_id(str(author[0])),
-                    "name": str(author[0]),
-                    "email": str(author[1]),
-                    # "github": ...
-                }
-                for author in authors
-            ]
-        },
+        "project": {"authors": entries},
     }
     update_authors_yml(data)
     click.echo("✓ Synced authors.yml with pyproject.toml")

src/afterpython/tools/myst.py

@@ -30,8 +30,7 @@ def update_authors_yml(data_update: dict):
     # merge authors, keep the author with more fields (e.g. github, x, etc.) to avoid duplication
     merged_authors = {}
     for author in (
-        existing_data["project"]["contributors"]
-        + data_update["project"]["contributors"]
+        existing_data["project"].get("authors", []) + data_update["project"]["authors"]
     ):
         author_id = author["id"]
         if author_id not in merged_authors:
@@ -40,14 +39,14 @@ def update_authors_yml(data_update: dict):
             # keep the author with more fields (e.g. github, x, etc.)
             if len(author.keys()) > len(merged_authors[author_id].keys()):
                 merged_authors[author_id] = author
-    existing_data["project"]["contributors"] = list(merged_authors.values())
+    existing_data["project"]["authors"] = list(merged_authors.values())
 
     # set comments for project section for convenience
     if "project" in existing_data and not existing_data["project"].ca.items.get(
-        "contributors"
+        "authors"
     ):
         existing_data["project"].yaml_set_comment_before_after_key(
-            "contributors",
+            "authors",
             before="See more at: https://mystmd.org/guide/frontmatter#frontmatter-authors",
         )
     write_yaml(file_path, existing_data)

src/afterpython/utils.py

@@ -149,6 +149,25 @@ def convert_author_name_to_id(name: str) -> str:
     return name.replace(" ", "_").lower()
 
 
+def build_author_name(name: str) -> dict:
+    """Build a MyST name object from a display name.
+
+    A multi-word name ("Stephen Yau") is split into ``given``/``surname`` so MyST
+    can render and cite it properly. A single-token name (e.g. a username like
+    "softwareentrepreneer") uses ``literal`` so MyST treats it as the full name
+    verbatim instead of warning about a missing given name.
+
+    Examples:
+        - "Stephen Yau" -> {"given": "Stephen", "surname": "Yau"}
+        - "softwareentrepreneer" -> {"literal": "softwareentrepreneer"}
+    """
+    name = name.strip()
+    if " " in name:
+        given, surname = name.split(" ", 1)
+        return {"given": given, "surname": surname}
+    return {"literal": name}
+
+
 def find_available_port(
     start_port: int = 3000, max_port: int = 3100, host: str = "localhost"
 ) -> int: