Skip to content

polish(nav): proper sidebar labels for SDK package groups #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WomB0ComB0 merged 1 commit into from
May 10, 2026
Merged

polish(nav): proper sidebar labels for SDK package groups #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 64 additions & 1 deletion automation/source-repo-templates/api-docs.rust.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,30 @@ jobs:
# (`resq-dsa`); convert with `-` → `_` to look them up.
rustdoc_md_dir = pathlib.Path("target") / "doc-md"

# Smart sidebar-label formatting (mirrors the splice
# step's helper) so leaf stub pages also read with proper
# acronyms and brand casing.
ACRONYMS = {
"ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp",
"ipfs", "grpc", "http", "url", "json", "yaml", "xml",
"sql", "css", "html", "io",
}
Comment on lines +211 to +215
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The ACRONYMS list is missing several project-specific and common technical acronyms that appear in the documentation (e.g., HCE, PDIE, DTSOP, RPC). Adding these will ensure they are correctly capitalized in the sidebar, matching the "polish" goal of this PR.

          ACRONYMS = {
              "ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp",
              "ipfs", "grpc", "http", "url", "json", "yaml", "xml",
              "sql", "css", "html", "io", "hce", "pdie", "dtsop", "rpc",
          }

BRAND = {"resq": "ResQ"}

def label_for(name: str) -> str:
if "." in name:
return name
out = []
for part in name.split("-"):
lower = part.lower()
if lower in BRAND:
out.append(BRAND[lower])
elif lower in ACRONYMS:
out.append(part.upper())
else:
out.append(part.capitalize())
return " ".join(out)
Comment on lines +218 to +230
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The label_for function has two opportunities for improvement:

  1. Underscore Handling: Rust and Python modules often use underscores (e.g., count_min). Currently, these would be rendered as Count_min instead of Count Min.
  2. Dot Heuristic: The check if "." in name is too broad. It correctly preserves .NET namespaces like ResQ.Blockchain, but it prevents polishing of lowercase TypeScript groups like after.fn or after.types. Refining this to only skip names with mixed casing (like the .NET examples) would fix this.
          def label_for(name: str) -> str:
              # Pass through names that already have mixed casing (e.g. .NET namespaces)
              if "." in name and not name.islower():
                  return name
              out = []
              # Handle both hyphens and underscores for consistent spacing
              for part in name.replace("_", "-").split("-"):
                  lower = part.lower()
                  if lower in BRAND:
                      out.append(BRAND[lower])
                  elif lower in ACRONYMS:
                      out.append(part.upper())
                  else:
                      out.append(part.capitalize())
              return " ".join(out)


def banner_for(meta: dict) -> str:
docs_rs_url = f"https://docs.rs/{meta['name']}/{meta['version']}"
crates_io_url = f"https://crates.io/crates/{meta['name']}"
Expand Down Expand Up @@ -252,7 +276,15 @@ jobs:
docs_rs_url = f"https://docs.rs/{meta['name']}/{meta['version']}"
crates_io_url = f"https://crates.io/crates/{meta['name']}"

# Frontmatter sidebarTitle gives the leaf a clean
# display label like "ResQ Clean" / "ResQ Deploy" so
# binary-only stubs match the style of library
# crates' rustdoc groups in the sidebar.
parts = [
"---",
f"sidebarTitle: '{label_for(meta['name'])}'",
"---",
"",
f"# {meta['name']}",
"",
f"> **Version:** `v{meta['version']}` · "
Expand Down Expand Up @@ -549,6 +581,35 @@ jobs:
parts = p.split("/")
insert_file(tree, parts, full_id)

# Smart group-label formatting so the sidebar reads
# "ResQ DSA" / "ResQ CLI" instead of the raw "resq-dsa" /
# "resq-cli" dir names. Acronyms upper-cased; the brand
# "ResQ" preserved with its mixed case; everything else
# title-cased. Result matches the brand voice and is
# consistent across all language sub-groups.
ACRONYMS = {
"ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp",
"ipfs", "grpc", "http", "url", "json", "yaml", "xml",
"sql", "css", "html", "io",
}
BRAND = {"resq": "ResQ"}

def label_for(name):
# Pass dotted names through (e.g. .NET-style
# `ResQ.Blockchain` already carry canonical casing).
if "." in name:
return name
out = []
for part in name.split("-"):
lower = part.lower()
if lower in BRAND:
out.append(BRAND[lower])
elif lower in ACRONYMS:
out.append(part.upper())
else:
out.append(part.capitalize())
return " ".join(out)
Comment on lines +590 to +611
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This logic is a duplicate of the label_for function defined earlier in the same file (lines 211-230). Additionally, the entire PYINNER block (lines 533-639) largely duplicates the logic found in scripts/splice-sdk-nav.py. Since this workflow already checks out the docs repository, it would be more maintainable to invoke the shared script directly rather than inlining a copy of the tree-building and label-formatting logic.


def to_mintlify(node, group_name):
pages = []
if "_landing" in node:
Expand All @@ -557,7 +618,9 @@ jobs:
pages.append(full_id)
for dname, sub in sorted(node.get("_dirs", {}).items()):
pages.append(to_mintlify(sub, dname))
return pages if group_name is None else {"group": group_name, "pages": pages}
if group_name is None:
return pages
return {"group": label_for(group_name), "pages": pages}

new_pages = [f"{PREFIX}/README"] + to_mintlify(tree, None)

Expand Down
Loading
Loading