Add sphinx build for vllm-ascend

Signed-off-by: Yikun Jiang <yikunkero@gmail.com>

.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
+

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.

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)反馈您的使用体验。

CONTRIBUTING.md → 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

CONTRIBUTING.zh.md → 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环境

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)
+

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.
+

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

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
+<p style="text-align:center">
+<strong>vLLM Ascend Plugin
+</strong>
+</p>
+
+<p style="text-align:center">
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+<a class="github-button" href="https://github.com/vllm-project/vllm-ascend" data-show-count="true" data-size="large" aria-label="Star">Star</a>
+<a class="github-button" href="https://github.com/vllm-project/vllm-ascend/subscription" data-icon="octicon-eye" data-size="large" aria-label="Watch">Watch</a>
+<a class="github-button" href="https://github.com/vllm-project/vllm-ascend/fork" data-icon="octicon-repo-forked" data-size="large" aria-label="Fork">Fork</a>
+</p>
+:::
+
 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
+:::

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