Skip to content

feat(rust-docs): render source README on each crate's landing page #68

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 2 commits into from
May 10, 2026
Merged

feat(rust-docs): render source README on each crate's landing page #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8a66ee
feat(rust-docs): render source README on each crate's landing page
resq-sw May 10, 2026
d04de09
fix(rust-docs): MDX-escape rebuilt landing pages
resq-sw May 10, 2026
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
64 changes: 52 additions & 12 deletions 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 @@ -252,22 +252,62 @@ jobs:
rustdoc_src = rustdoc_md_dir / meta["lib_name"]
if rustdoc_src.is_dir():
# Rich rustdoc output exists. Copy the whole tree
# into OUTPUT_DIR/<crate>/ and inject the version
# banner after the H1 of the landing index.md.
# into OUTPUT_DIR/<crate>/, then REPLACE the
# auto-generated index.md with a hybrid landing:
#
# 1. version banner
# 2. cleaned README.md from the crate source
# (mermaid diagrams, badges, install
# instructions, etc. — the human-readable
# intro that cargo-doc-md doesn't produce)
# 3. ## Modules section linking to each
# cargo-doc-md per-module page
#
# The original cargo-doc-md index.md content (just
# the lib.rs //! doc + a flat module list) is
# dropped because the README provides the same
# information more richly, and the per-module pages
# keep the full API surface intact.
dest = out_root / meta["name"]
if dest.exists():
shutil.rmtree(dest)
shutil.copytree(rustdoc_src, dest)
landing = dest / "index.md"
if landing.is_file():
text = landing.read_text(encoding="utf-8")
h1 = re.match(r"(# [^\n]+\n+)", text)
banner = banner_for(meta)
if h1:
text = text[: h1.end()] + banner + text[h1.end():]
else:
text = banner + text
landing.write_text(text, encoding="utf-8")

module_files = sorted(
p for p in dest.iterdir()
if p.is_file()
and p.suffix == ".md"
and p.stem not in ("index", meta["lib_name"])
)
module_lines = [
f"- [`{p.stem}`](./{p.stem})"
for p in module_files
]
Comment on lines +282 to +285
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.

high

The generated links for modules are missing the .md extension. Since the files on disk retain the .md suffix (as seen in the filtering logic at line 279), these links will likely fail to resolve in the documentation site. Additionally, the post-processing script that prefixes relative links (lines 371-408) specifically looks for the .md extension, so these links will be skipped by that safety check as well.

                  module_lines = [
                      f"- [{p.stem}](./{p.name})"
                      for p in module_files
                  ]


readme = crate_dir / "README.md"
body_parts = [f"# {meta['name']}", "", banner_for(meta).rstrip(), ""]
if readme.is_file():
body = readme.read_text(encoding="utf-8")
body = re.sub(r"^\s*<!--.*?-->\s*", "", body, count=1, flags=re.S)
body = re.sub(r"^#\s+[^\n]+\n+", "", body, count=1)
body = rewrite_relative_links(body, crate_dir)
body_parts.extend([body.rstrip(), ""])
Comment on lines +288 to +294
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

For crates without a README.md (such as resq-ai), this change results in a landing page that lacks any description of the crate's purpose, losing information that was previously extracted from the lib.rs doc comments. To maintain documentation quality, consider falling back to the description field from Cargo.toml when the README is missing, similar to the logic used for binary stubs at line 336.

                  body_parts = [f"# {meta['name']}", "", banner_for(meta).rstrip(), ""]
                  if readme.is_file():
                      body = readme.read_text(encoding="utf-8")
                      body = re.sub(r"^\s*<!--.*?-->\s*", "", body, count=1, flags=re.S)
                      body = re.sub(r"^#\s+[^\n]+\n+", "", body, count=1)
                      body = rewrite_relative_links(body, crate_dir)
                      body_parts.extend([body.rstrip(), ""])
                  elif meta["description"]:
                      body_parts.extend([meta["description"], ""])


if module_lines:
body_parts.extend([
"## Modules",
"",
"Click through to each module for the full "
"rustdoc-rendered API surface (types, traits, "
"functions, methods).",
"",
*module_lines,
"",
])

(dest / "index.md").write_text(
"\n".join(body_parts) + "\n", encoding="utf-8"
)
rendered += 1
print(f" rustdoc: {meta['name']}")
continue
Expand Down
21 changes: 5 additions & 16 deletions sdks/rust/api/resq-ai/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,12 @@
# resq_ai
# resq-ai

> **Version:** `v0.1.0` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-ai) · **API docs:** [docs.rs](https://docs.rs/resq-ai/0.1.0)

Multi-provider LLM abstraction for `ResQ` developer tools.

Supports Anthropic, `OpenAI`, and Google Gemini APIs with a unified
`complete()` interface and cascading config resolution.

## Modules

### [`config`](./config.md)

*1 function, 1 struct*

### [`provider`](./provider.md)

*1 enum, 1 function*

### [`token`](./token.md)
Click through to each module for the full rustdoc-rendered API surface (types, traits, functions, methods).

*2 functions*
- [`config`](./config)
- [`provider`](./provider)
- [`token`](./token)

Loading
Loading