conf.py 8.42 KB
Newer Older
1
2
# SPDX-License-Identifier: Apache-2.0

Woosuk Kwon's avatar
Woosuk Kwon committed
3
4
5
6
7
8
9
10
11
12
13
14
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.

15
import datetime
16
import logging
17
import os
18
import re
19
import sys
20
from pathlib import Path
21

22
import requests
23
24

logger = logging.getLogger(__name__)
25
26
REPO_ROOT = Path(__file__).resolve().parent.parent.parent
sys.path.append(os.path.abspath(REPO_ROOT))
Woosuk Kwon's avatar
Woosuk Kwon committed
27
28
29

# -- Project information -----------------------------------------------------

Woosuk Kwon's avatar
Woosuk Kwon committed
30
project = 'vLLM'
31
copyright = f'{datetime.datetime.now().year}, vLLM Team'
Woosuk Kwon's avatar
Woosuk Kwon committed
32
author = 'the vLLM Team'
Woosuk Kwon's avatar
Woosuk Kwon committed
33
34
35
36
37
38
39
40

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx.ext.napoleon",
41
    "sphinx.ext.linkcode",
Woosuk Kwon's avatar
Woosuk Kwon committed
42
43
    "sphinx.ext.intersphinx",
    "sphinx_copybutton",
44
    "autodoc2",
45
46
    "myst_parser",
    "sphinxarg.ext",
47
    "sphinx_design",
48
49
50
51
    "sphinx_togglebutton",
]
myst_enable_extensions = [
    "colon_fence",
52
    "fieldlist",
Woosuk Kwon's avatar
Woosuk Kwon committed
53
]
54
55
56
57
58
59
60
61
62
63
64
65
66
67
autodoc2_packages = [
    {
        "path": "../../vllm",
        "exclude_dirs": ["__pycache__", "third_party"],
    },
]
autodoc2_output_dir = "api"
autodoc2_render_plugin = "myst"
autodoc2_hidden_objects = ["dunder", "private", "inherited"]
autodoc2_docstring_parser_regexes = [
    (".*", "docs.source.autodoc2_docstring_parser"),
]
autodoc2_sort_names = True
autodoc2_index_template = None
Woosuk Kwon's avatar
Woosuk Kwon committed
68
69
70
71
72
73
74

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
75
exclude_patterns: list[str] = ["**/*.template.md", "**/*.inc.md"]
Woosuk Kwon's avatar
Woosuk Kwon committed
76
77
78
79
80
81
82
83
84
85
86
87

# Exclude the prompt "$" when copying code
copybutton_prompt_text = r"\$ "
copybutton_prompt_is_regexp = True

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_title = project
html_theme = 'sphinx_book_theme'
88
html_logo = 'assets/logos/vllm-logo-text-light.png'
Harry Mellor's avatar
Harry Mellor committed
89
html_favicon = 'assets/logos/vllm-logo-only-light.ico'
Woosuk Kwon's avatar
Woosuk Kwon committed
90
91
html_theme_options = {
    'path_to_docs': 'docs/source',
92
    'repository_url': 'https://github.com/vllm-project/vllm',
Woosuk Kwon's avatar
Woosuk Kwon committed
93
    'use_repository_button': True,
94
    'use_edit_page_button': True,
95
96
97
98
99
    # Prevents the full API being added to the left sidebar of every page.
    # Reduces build time by 2.5x and reduces build size from ~225MB to ~95MB.
    'collapse_navbar': True,
    # Makes API visible in the right sidebar on API reference pages.
    'show_toc_level': 3,
Woosuk Kwon's avatar
Woosuk Kwon committed
100
}
101
102
103
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
104
105
html_static_path = ["_static"]
html_js_files = ["custom.js"]
106
html_css_files = ["custom.css"]
Woosuk Kwon's avatar
Woosuk Kwon committed
107

108
myst_heading_anchors = 2
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
myst_url_schemes = {
    'http': None,
    'https': None,
    'mailto': None,
    'ftp': None,
    "gh-issue": {
        "url":
        "https://github.com/vllm-project/vllm/issues/{{path}}#{{fragment}}",
        "title": "Issue #{{path}}",
        "classes": ["github"],
    },
    "gh-pr": {
        "url":
        "https://github.com/vllm-project/vllm/pull/{{path}}#{{fragment}}",
        "title": "Pull Request #{{path}}",
        "classes": ["github"],
    },
126
    "gh-project": {
127
        "url": "https://github.com/orgs/vllm-project/projects/{{path}}",
128
129
130
        "title": "Project #{{path}}",
        "classes": ["github"],
    },
131
132
133
134
135
136
137
138
139
140
141
142
    "gh-dir": {
        "url": "https://github.com/vllm-project/vllm/tree/main/{{path}}",
        "title": "{{path}}",
        "classes": ["github"],
    },
    "gh-file": {
        "url": "https://github.com/vllm-project/vllm/blob/main/{{path}}",
        "title": "{{path}}",
        "classes": ["github"],
    },
}

143
144
145
146
147
148
# see https://docs.readthedocs.io/en/stable/reference/environment-variables.html # noqa
READTHEDOCS_VERSION_TYPE = os.environ.get('READTHEDOCS_VERSION_TYPE')
if READTHEDOCS_VERSION_TYPE == "tag":
    # remove the warning banner if the version is a tagged release
    header_file = os.path.join(os.path.dirname(__file__),
                               "_templates/sections/header.html")
149
150
151
152
    # The file might be removed already if the build is triggered multiple times
    # (readthedocs build both HTML and PDF versions separately)
    if os.path.exists(header_file):
        os.remove(header_file)
153

154
155
156
157
158
159
160

# Generate additional rst documentation here.
def setup(app):
    from docs.source.generate_examples import generate_examples
    generate_examples()


161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
_cached_base: str = ""
_cached_branch: str = ""


def get_repo_base_and_branch(pr_number):
    global _cached_base, _cached_branch
    if _cached_base and _cached_branch:
        return _cached_base, _cached_branch

    url = f"https://api.github.com/repos/vllm-project/vllm/pulls/{pr_number}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        _cached_base = data['head']['repo']['full_name']
        _cached_branch = data['head']['ref']
        return _cached_base, _cached_branch
    else:
        logger.error("Failed to fetch PR details: %s", response)
        return None, None


def linkcode_resolve(domain, info):
    if domain != 'py':
        return None
    if not info['module']:
        return None
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

    # Get path from module name
    file = Path(f"{info['module'].replace('.', '/')}.py")
    path = REPO_ROOT / file
    if not path.exists():
        path = REPO_ROOT / file.with_suffix("") / "__init__.py"
    if not path.exists():
        return None

    # Get the line number of the object
    with open(path) as f:
        lines = f.readlines()
    name = info['fullname'].split(".")[-1]
    pattern = fr"^( {{4}})*((def|class) )?{name}\b.*"
    for lineno, line in enumerate(lines, 1):
        if not line or line.startswith("#"):
            continue
        if re.match(pattern, line):
            break

    # If the line number is not found, return None
    if lineno == len(lines):
        return None

    # If the line number is found, create the URL
    filename = path.relative_to(REPO_ROOT)
    if "checkouts" in path.parts:
214
        # a PR build on readthedocs
215
        pr_number = REPO_ROOT.name
216
217
218
219
220
221
222
        base, branch = get_repo_base_and_branch(pr_number)
        if base and branch:
            return f"https://github.com/{base}/blob/{branch}/{filename}#L{lineno}"
    # Otherwise, link to the source file on the main branch
    return f"https://github.com/vllm-project/vllm/blob/main/{filename}#L{lineno}"


223
# Mock out external dependencies here, otherwise sphinx-argparse won't work.
224
autodoc_mock_imports = [
225
226
227
228
229
230
    "huggingface_hub",
    "pydantic",
    "zmq",
    "cloudpickle",
    "aiohttp",
    "starlette",
231
    "blake3",
232
    "cpuinfo",
233
234
235
    "transformers",
    "psutil",
    "vllm._C",
236
    "PIL",
237
238
    "numpy",
    "tqdm",
239
240
241
242
243
244
    # The mocks below are required by
    # docs/source/serving/openai_compatible_server.md's
    # vllm.entrypoints.openai.cli_args
    "openai",
    "fastapi",
    "partial_json_parser",
245
246
247
248
249
]

for mock_target in autodoc_mock_imports:
    if mock_target in sys.modules:
        logger.info(
250
            "Potentially problematic mock target (%s) found; "
251
            "autodoc_mock_imports cannot mock modules that have already "
252
253
            "been loaded into sys.modules when the sphinx build starts.",
            mock_target)
254

255
intersphinx_mapping = {
256
257
258
    "python": ("https://docs.python.org/3", None),
    "typing_extensions":
    ("https://typing-extensions.readthedocs.io/en/latest", None),
259
    "aiohttp": ("https://docs.aiohttp.org/en/stable", None),
260
261
262
263
    "pillow": ("https://pillow.readthedocs.io/en/stable", None),
    "numpy": ("https://numpy.org/doc/stable", None),
    "torch": ("https://pytorch.org/docs/stable", None),
    "psutil": ("https://psutil.readthedocs.io/en/stable", None),
264
265
}

266
navigation_with_keys = False