A high-throughput and memory-efficient inference and serving engine for LLMs
Mirrored from https://github.com/tduncan-lum/Nvidia-Optimization-Stack---VLLM.git
Synced Nov 15, 03:30 UTC
Add docstrings to url_schemes.py to improve readability (#20545)
Signed-off-by: windsonsea <haifeng.yao@daocloud.io>
Michael Yao committed
Jul 7, 2025 at 16:31 UTC
1fd471e957526a34a0cb4b60d2e830cd6ca79fdc
1 file changed
+69
-1
docs/mkdocs/hooks/url_schemes.py
+69
-1
@@ -1,5 +1,24 @@
1
# SPDX-License-Identifier: Apache-2.0
2
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
3
+"""
4
+This is basically a port of MyST parser’s external URL resolution mechanism
5
+(https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#customising-external-url-resolution)
6
+to work with MkDocs.
7
+
8
+It allows Markdown authors to use GitHub shorthand links like:
9
+
10
+ - [Text](gh-issue:123)
11
+ - <gh-pr:456>
12
+ - [File](gh-file:path/to/file.py#L10)
13
+
14
+These are automatically rewritten into fully qualified GitHub URLs pointing to
15
+issues, pull requests, files, directories, or projects in the
16
+`vllm-project/vllm` repository.
17
+
18
+The goal is to simplify cross-referencing common GitHub resources
19
+in project docs.
20
+"""
21
+
22
import regex as re
23
from mkdocs.config.defaults import MkDocsConfig
24
from mkdocs.structure.files import Files
@@ -7,11 +26,42 @@ from mkdocs.structure.pages import Page
26
27
28
def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig,
10
- files: Files):
29
+ files: Files) -> str:
30
+ """
31
+ Custom MkDocs plugin hook to rewrite special GitHub reference links
32
+ in Markdown.
33
+
34
+ This function scans the given Markdown content for specially formatted
35
+ GitHub shorthand links, such as:
36
+ - `[Link text](gh-issue:123)`
37
+ - `<gh-pr:456>`
38
+
39
+ And rewrites them into fully-qualified GitHub URLs with GitHub icons:
40
+ - `[:octicons-mark-github-16: Link text](https://github.com/vllm-project/vllm/issues/123)`
41
+ - `[:octicons-mark-github-16: Pull Request #456](https://github.com/vllm-project/vllm/pull/456)`
42
+
43
+ Supported shorthand types:
44
+ - `gh-issue`
45
+ - `gh-pr`
46
+ - `gh-project`
47
+ - `gh-dir`
48
+ - `gh-file`
49
+
50
+ Args:
51
+ markdown (str): The raw Markdown content of the page.
52
+ page (Page): The MkDocs page object being processed.
53
+ config (MkDocsConfig): The MkDocs site configuration.
54
+ files (Files): The collection of files in the MkDocs build.
55
+
56
+ Returns:
57
+ str: The updated Markdown content with GitHub shorthand links replaced.
58
+ """
59
gh_icon = ":octicons-mark-github-16:"
60
gh_url = "https://github.com"
61
repo_url = f"{gh_url}/vllm-project/vllm"
62
org_url = f"{gh_url}/orgs/vllm-project"
63
+
64
+ # Mapping of shorthand types to their corresponding GitHub base URLs
65
urls = {
66
"issue": f"{repo_url}/issues",
67
"pr": f"{repo_url}/pull",
@@ -19,6 +69,8 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig,
69
"dir": f"{repo_url}/tree/main",
70
"file": f"{repo_url}/blob/main",
71
}
72
+
73
+ # Default title prefixes for auto links
74
titles = {
75
"issue": "Issue #",
76
"pr": "Pull Request #",
@@ -27,11 +79,19 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig,
79
"file": "",
80
}
81
82
+ # Regular expression to match GitHub shorthand links
83
scheme = r"gh-(?P<type>.+?):(?P<path>.+?)(#(?P<fragment>.+?))?"
84
inline_link = re.compile(r"\[(?P<title>[^\[]+?)\]\(" + scheme + r"\)")
85
auto_link = re.compile(f"<{scheme}>")
86
87
def replace_inline_link(match: re.Match) -> str:
88
+ """
89
+ Replaces a matched inline-style GitHub shorthand link
90
+ with a full Markdown link.
91
+
92
+ Example:
93
+ [My issue](gh-issue:123) → [:octicons-mark-github-16: My issue](https://github.com/vllm-project/vllm/issues/123)
94
+ """
95
url = f'{urls[match.group("type")]}/{match.group("path")}'
96
if fragment := match.group("fragment"):
97
url += f"#{fragment}"
@@ -39,6 +99,13 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig,
99
return f'[{gh_icon} {match.group("title")}]({url})'
100
101
def replace_auto_link(match: re.Match) -> str:
102
+ """
103
+ Replaces a matched autolink-style GitHub shorthand
104
+ with a full Markdown link.
105
+
106
+ Example:
107
+ <gh-pr:456> → [:octicons-mark-github-16: Pull Request #456](https://github.com/vllm-project/vllm/pull/456)
108
+ """
109
type = match.group("type")
110
path = match.group("path")
111
title = f"{titles[type]}{path}"
@@ -48,6 +115,7 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig,
115
116
return f"[{gh_icon} {title}]({url})"
117
118
+ # Replace both inline and autolinks
119
markdown = inline_link.sub(replace_inline_link, markdown)
120
markdown = auto_link.sub(replace_auto_link, markdown)
121