From e114608558a1cdf746a66db11fd140a227f02324 Mon Sep 17 00:00:00 2001 From: Yikun Jiang Date: Thu, 13 Feb 2025 00:03:00 +0800 Subject: [PATCH] Add sphinx build for vllm-ascend Signed-off-by: Yikun Jiang --- .readthedocs.yaml | 22 +++++ README.md | 2 +- README.zh.md | 2 +- CONTRIBUTING.md => docs/CONTRIBUTING.md | 4 +- CONTRIBUTING.zh.md => docs/CONTRIBUTING.zh.md | 2 +- docs/Makefile | 21 +++++ docs/README.md | 21 +++++ docs/conf.py | 82 +++++++++++++++++++ docs/index.md | 54 ++++++++++-- docs/requirements-docs.txt | 8 ++ 10 files changed, 205 insertions(+), 13 deletions(-) create mode 100644 .readthedocs.yaml rename CONTRIBUTING.md => docs/CONTRIBUTING.md (96%) rename CONTRIBUTING.zh.md => docs/CONTRIBUTING.zh.md (94%) create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/conf.py create mode 100644 docs/requirements-docs.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..916d3b9f --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + fail_on_warning: true + +# If using Sphinx, optionally build your docs in additional formats such as PDF +formats: [] + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements-docs.txt + diff --git a/README.md b/README.md index 52c1e31b..9e9a12e7 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ curl http://localhost:8000/v1/models **Please refer to [Official Docs](./docs/index.md) for more details.** ## Contributing -See [CONTRIBUTING](./CONTRIBUTING.md) for more details, which is a step-by-step guide to help you set up development environment, build and test. +See [CONTRIBUTING](docs/CONTRIBUTING.md) for more details, which is a step-by-step guide to help you set up development environment, build and test. We welcome and value any contributions and collaborations: - Please feel free comments [here](https://github.com/vllm-project/vllm-ascend/issues/19) about your usage of vLLM Ascend Plugin. diff --git a/README.zh.md b/README.zh.md index f5addc46..851da6c8 100644 --- a/README.zh.md +++ b/README.zh.md @@ -68,7 +68,7 @@ curl http://localhost:8000/v1/models **请参阅 [官方文档](./docs/index.md)以获取更多详细信息** ## 贡献 -有关更多详细信息，请参阅 [CONTRIBUTING](./CONTRIBUTING.md)，可以更详细的帮助您部署开发环境、构建和测试。 +有关更多详细信息，请参阅 [CONTRIBUTING](docs/CONTRIBUTING.md)，可以更详细的帮助您部署开发环境、构建和测试。 我们欢迎并重视任何形式的贡献与合作： - 您可以在[这里](https://github.com/vllm-project/vllm-ascend/issues/19)反馈您的使用体验。 diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 96% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md index c7d45f68..1d36987c 100644 --- a/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to vLLM Ascend plugin +# Contributing ## Building and testing It's recommended to set up a local development environment to build and test @@ -45,7 +45,7 @@ git commit -sm "your commit info" ### Testing -Although vllm-ascend CI provide integration test on [Ascend](.github/workflows/vllm_ascend_test.yaml), you can run it +Although vllm-ascend CI provide integration test on [Ascend](../.github/workflows/vllm_ascend_test.yaml), you can run it locally. The simplest way to run these integration tests locally is through a container: ```bash diff --git a/CONTRIBUTING.zh.md b/docs/CONTRIBUTING.zh.md similarity index 94% rename from CONTRIBUTING.zh.md rename to docs/CONTRIBUTING.zh.md index 259bc56e..5639b026 100644 --- a/CONTRIBUTING.zh.md +++ b/docs/CONTRIBUTING.zh.md @@ -41,7 +41,7 @@ git commit -sm "your commit info" ``` ### 测试 -虽然 vllm-ascend CI 提供了对 [Ascend](.github/workflows/vllm_ascend_test.yaml) 的集成测试，但您也可以在本地运行它。在本地运行这些集成测试的最简单方法是通过容器： +虽然 vllm-ascend CI 提供了对 [Ascend](../.github/workflows/vllm_ascend_test.yaml) 的集成测试，但您也可以在本地运行它。在本地运行这些集成测试的最简单方法是通过容器： ```bash # 基于昇腾NPU环境 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..b2e992ee --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,21 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..312712a6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +# vLLM Ascend Plugin documents + +## Build the docs + +```bash +# Install dependencies. +pip install -r requirements-docs.txt + +# Build the docs. +make clean +make html +``` + +## Open the docs with your browser + +```bash +python -m http.server -d build/html/ +``` + +Launch your browser and open localhost:8000. + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..601d999a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,82 @@ +# -- 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'vLLM Ascend Plugin' +copyright = '2025, vllm-ascend Team' +author = 'the vllm-ascend Team' + +# The full version, including alpha/beta/rc tags +release = '' + + +# -- 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. + +# Copy from https://github.com/vllm-project/vllm/blob/main/docs/source/conf.py +extensions = [ + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx_copybutton", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "myst_parser", + "sphinxarg.ext", + "sphinx_design", + "sphinx_togglebutton", +] +myst_enable_extensions = [ + "colon_fence", +] + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# 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. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.venv', 'README.md'] + + +# -- 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' +html_logo = 'logos/vllm-ascend-logo-text-light.png' +html_theme_options = { + 'path_to_docs': 'docs/source', + 'repository_url': 'https://github.com/vllm-project/vllm-ascend', + 'use_repository_button': True, + 'use_edit_page_button': True, +} +# 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". +# html_static_path = ['_static'] + + +def setup(app): + pass diff --git a/docs/index.md b/docs/index.md index 860501b3..659c65f6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,53 @@ -# Ascend plugin for vLLM +# Welcome to vLLM Ascend Plugin + +:::{figure} ./logos/vllm-ascend-logo-text-light.png +:align: center +:alt: vLLM +:class: no-scaled-link +:width: 70% +::: + +:::{raw} html +

+vLLM Ascend Plugin + +

+ +

+ +Star +Watch +Fork +

+::: + vLLM Ascend plugin (vllm-ascend) is a community maintained hardware plugin for running vLLM on the Ascend NPU. This plugin is the recommended approach for supporting the Ascend backend within the vLLM community. It adheres to the principles outlined in the [[RFC]: Hardware pluggable](https://github.com/vllm-project/vllm/issues/11162), providing a hardware-pluggable interface that decouples the integration of the Ascend NPU with vLLM. By using vLLM Ascend plugin, popular open-source models, including Transformer-like, Mixture-of-Expert, Embedding, Multi-modal LLMs can run seamlessly on the Ascend NPU. -## Contents +## Documentation + +% How to start using vLLM on Ascend NPU? +:::{toctree} +:caption: Getting Started +:maxdepth: 1 +quick_start +installation +::: + +% What does vLLM Ascend Plugin support? +:::{toctree} +:caption: Features +:maxdepth: 1 +usage/feature_support +usage/supported_models +::: -- [Quick Start](./quick_start.md) -- [Installation](./installation.md) -- Usage - - [Running vLLM with Ascend](./usage/running_vllm_with_ascend.md) - - [Feature Support](./usage/feature_support.md) - - [Supported Models](./usage/supported_models.md) +% How to contribute to the vLLM project +:::{toctree} +:caption: Developer Guide +:maxdepth: 1 +CONTRIBUTING +::: \ No newline at end of file diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 00000000..e837e992 --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,8 @@ +sphinx==6.2.1 +sphinx-argparse==0.4.0 +sphinx-book-theme==1.0.1 +sphinx-copybutton==0.5.2 +sphinx-design==0.6.1 +sphinx-togglebutton==0.3.2 +myst-parser==3.0.1 +msgspec