[Docs] Reduce custom syntax used in docs (#27009)
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
This commit is contained in:
Harry Mellor
@@ -1,123 +1,95 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
|
||||
"""
|
||||
This is basically a port of MyST parser’s external URL resolution mechanism
|
||||
(https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#customising-external-url-resolution)
|
||||
to work with MkDocs.
|
||||
MkDocs hook to enable the following links to render correctly:
|
||||
|
||||
It allows Markdown authors to use GitHub shorthand links like:
|
||||
|
||||
- [Text](gh-issue:123)
|
||||
- <gh-pr:456>
|
||||
- [File](gh-file:path/to/file.py#L10)
|
||||
|
||||
These are automatically rewritten into fully qualified GitHub URLs pointing to
|
||||
issues, pull requests, files, directories, or projects in the
|
||||
`vllm-project/vllm` repository.
|
||||
- Relative file links outside of the `docs/` directory, e.g.:
|
||||
- [Text](../some_file.py)
|
||||
- [Directory](../../some_directory/)
|
||||
- GitHub URLs for issues, pull requests, and projects, e.g.:
|
||||
- Adds GitHub icon before links
|
||||
- Replaces raw links with descriptive text,
|
||||
e.g. <...pull/123> -> [Pull Request #123](.../pull/123)
|
||||
- Works for external repos too by including the `owner/repo` in the link title
|
||||
|
||||
The goal is to simplify cross-referencing common GitHub resources
|
||||
in project docs.
|
||||
"""
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
import regex as re
|
||||
from mkdocs.config.defaults import MkDocsConfig
|
||||
from mkdocs.structure.files import Files
|
||||
from mkdocs.structure.pages import Page
|
||||
|
||||
ROOT_DIR = Path(__file__).parent.parent.parent.parent.resolve()
|
||||
DOC_DIR = ROOT_DIR / "docs"
|
||||
|
||||
|
||||
gh_icon = ":octicons-mark-github-16:"
|
||||
|
||||
# Regex pieces
|
||||
TITLE = r"(?P<title>[^\[\]<>]+?)"
|
||||
REPO = r"(?P<repo>.+?/.+?)"
|
||||
TYPE = r"(?P<type>issues|pull|projects)"
|
||||
NUMBER = r"(?P<number>\d+)"
|
||||
FRAGMENT = r"(?P<fragment>#[^\s]+)?"
|
||||
URL = f"https://github.com/{REPO}/{TYPE}/{NUMBER}{FRAGMENT}"
|
||||
RELATIVE = r"(?!(https?|ftp)://|#)(?P<path>[^\s]+?)"
|
||||
|
||||
# Common titles to use for GitHub links when none is provided in the link.
|
||||
TITLES = {"issues": "Issue ", "pull": "Pull Request ", "projects": "Project "}
|
||||
|
||||
# Regex to match GitHub issue, PR, and project links with optional titles.
|
||||
github_link = re.compile(rf"(\[{TITLE}\]\(|<){URL}(\)|>)")
|
||||
# Regex to match relative file links with optional titles.
|
||||
relative_link = re.compile(rf"\[{TITLE}\]\({RELATIVE}\)")
|
||||
|
||||
|
||||
def on_page_markdown(
|
||||
markdown: str, *, page: Page, config: MkDocsConfig, files: Files
|
||||
) -> str:
|
||||
"""
|
||||
Custom MkDocs plugin hook to rewrite special GitHub reference links
|
||||
in Markdown.
|
||||
|
||||
This function scans the given Markdown content for specially formatted
|
||||
GitHub shorthand links, such as:
|
||||
- `[Link text](gh-issue:123)`
|
||||
- `<gh-pr:456>`
|
||||
|
||||
And rewrites them into fully-qualified GitHub URLs with GitHub icons:
|
||||
- `[:octicons-mark-github-16: Link text](https://github.com/vllm-project/vllm/issues/123)`
|
||||
- `[:octicons-mark-github-16: Pull Request #456](https://github.com/vllm-project/vllm/pull/456)`
|
||||
|
||||
Supported shorthand types:
|
||||
- `gh-issue`
|
||||
- `gh-pr`
|
||||
- `gh-project`
|
||||
- `gh-dir`
|
||||
- `gh-file`
|
||||
|
||||
Args:
|
||||
markdown (str): The raw Markdown content of the page.
|
||||
page (Page): The MkDocs page object being processed.
|
||||
config (MkDocsConfig): The MkDocs site configuration.
|
||||
files (Files): The collection of files in the MkDocs build.
|
||||
|
||||
Returns:
|
||||
str: The updated Markdown content with GitHub shorthand links replaced.
|
||||
"""
|
||||
gh_icon = ":octicons-mark-github-16:"
|
||||
gh_url = "https://github.com"
|
||||
repo_url = f"{gh_url}/vllm-project/vllm"
|
||||
org_url = f"{gh_url}/orgs/vllm-project"
|
||||
|
||||
# Mapping of shorthand types to their corresponding GitHub base URLs
|
||||
urls = {
|
||||
"issue": f"{repo_url}/issues",
|
||||
"pr": f"{repo_url}/pull",
|
||||
"project": f"{org_url}/projects",
|
||||
"dir": f"{repo_url}/tree/main",
|
||||
"file": f"{repo_url}/blob/main",
|
||||
}
|
||||
|
||||
# Default title prefixes for auto links
|
||||
titles = {
|
||||
"issue": "Issue #",
|
||||
"pr": "Pull Request #",
|
||||
"project": "Project #",
|
||||
"dir": "",
|
||||
"file": "",
|
||||
}
|
||||
|
||||
# Regular expression to match GitHub shorthand links
|
||||
scheme = r"gh-(?P<type>.+?):(?P<path>.+?)(#(?P<fragment>.+?))?"
|
||||
inline_link = re.compile(r"\[(?P<title>[^\[]+?)\]\(" + scheme + r"\)")
|
||||
auto_link = re.compile(f"<{scheme}>")
|
||||
|
||||
def replace_inline_link(match: re.Match) -> str:
|
||||
"""
|
||||
Replaces a matched inline-style GitHub shorthand link
|
||||
with a full Markdown link.
|
||||
|
||||
Example:
|
||||
[My issue](gh-issue:123) → [:octicons-mark-github-16: My issue](https://github.com/vllm-project/vllm/issues/123)
|
||||
"""
|
||||
url = f"{urls[match.group('type')]}/{match.group('path')}"
|
||||
if fragment := match.group("fragment"):
|
||||
url += f"#{fragment}"
|
||||
|
||||
return f"[{gh_icon} {match.group('title')}]({url})"
|
||||
|
||||
def replace_auto_link(match: re.Match) -> str:
|
||||
"""
|
||||
Replaces a matched autolink-style GitHub shorthand
|
||||
with a full Markdown link.
|
||||
|
||||
Example:
|
||||
<gh-pr:456> → [:octicons-mark-github-16: Pull Request #456](https://github.com/vllm-project/vllm/pull/456)
|
||||
"""
|
||||
type = match.group("type")
|
||||
def replace_relative_link(match: re.Match) -> str:
|
||||
"""Replace relative file links with URLs if they point outside the docs dir."""
|
||||
title = match.group("title")
|
||||
path = match.group("path")
|
||||
title = f"{titles[type]}{path}"
|
||||
url = f"{urls[type]}/{path}"
|
||||
if fragment := match.group("fragment"):
|
||||
url += f"#{fragment}"
|
||||
path = (Path(page.file.abs_src_path).parent / path).resolve()
|
||||
|
||||
# Check if the path exists and is outside the docs dir
|
||||
if not path.exists() or path.is_relative_to(DOC_DIR):
|
||||
return match.group(0)
|
||||
|
||||
# Files and directories have different URL schemes on GitHub
|
||||
slug = "tree/main" if path.is_dir() else "blob/main"
|
||||
|
||||
path = path.relative_to(ROOT_DIR)
|
||||
url = f"https://github.com/vllm-project/vllm/{slug}/{path}"
|
||||
return f"[{gh_icon} {title}]({url})"
|
||||
|
||||
# Replace both inline and autolinks
|
||||
markdown = inline_link.sub(replace_inline_link, markdown)
|
||||
markdown = auto_link.sub(replace_auto_link, markdown)
|
||||
def replace_github_link(match: re.Match) -> str:
|
||||
"""Replace GitHub issue, PR, and project links with enhanced Markdown links."""
|
||||
repo = match.group("repo")
|
||||
type = match.group("type")
|
||||
number = match.group("number")
|
||||
# Title and fragment could be None
|
||||
title = match.group("title") or ""
|
||||
fragment = match.group("fragment") or ""
|
||||
|
||||
# Use default titles for raw links
|
||||
if not title:
|
||||
title = TITLES[type]
|
||||
if "vllm-project" not in repo:
|
||||
title += repo
|
||||
title += f"#{number}"
|
||||
|
||||
url = f"https://github.com/{repo}/{type}/{number}{fragment}"
|
||||
return f"[{gh_icon} {title}]({url})"
|
||||
|
||||
markdown = relative_link.sub(replace_relative_link, markdown)
|
||||
markdown = github_link.sub(replace_github_link, markdown)
|
||||
|
||||
if "interface" in str(page.file.abs_src_path):
|
||||
print(markdown)
|
||||
|
||||
return markdown
|
||||
|
||||
Reference in New Issue
Block a user