背景简介
配置 Sphinx 和 CICD 自动化部署。
前置信息
- Python 项目已完成
详细信息
项目结构
.
├── alembic
│ ├── versions
│ │ └── ebbc6e3a391e_create_user_basic_info_table.py
│ ├── env.py
│ └── script.py.mako
├── app
│ ├── api
│ │ └── v1
│ │ └── health.py
│ ├── core
│ │ ├── config.py
│ │ ├── database.py
│ │ └── __init__.py
│ ├── models
│ │ ├── __init__.py
│ │ └── user_basic_info.py
│ ├── __init__.py
│ └── main.py
├── ci
│ └── backend-deploy.sh
├── docs
│ ├── _static
│ ├── _templates
│ ├── app.core.rst
│ ├── app.models.rst
│ ├── app.rst
│ ├── conf.py
│ ├── index.rst
│ ├── Makefile
│ └── modules.rst
├── .gitea
│ └── workflows
│ └── backend.yml
├── tests
│ └── test_health.py
├── alembic.ini
├── docker-compose.yml
├── Dockerfile
├── .env
├── pytest.ini
├── requirements-dev.txt
├── requirements-docs.txt
└── requirements.txt
环境依赖
sphinx
sphinx-rtd-theme # 可选：常用主题，便于阅读（可换成你喜欢的主题）
sphinx-autodoc-typehints # 可选：更好地显示类型注解
准备配置文件
- 准备：
requirements-docs.txt
-r requirements.txt
sphinx
sphinx-rtd-theme # 可选：常用主题，便于阅读（可换成你喜欢的主题）
sphinx-autodoc-typehints # 可选：更好地显示类型注解
- 准备：
docs/conf.py
import os
import sys
from datetime import datetime
# add project root to sys.path so autodoc can import your app modules
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
sys.path.insert(0, PROJECT_ROOT)
project = "your-project-name"
author = "Your Name or Org"
release = "0.0.0"
copyright = f"{datetime.now().year}, {author}"
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.napoleon", # 支持 Google/NumPy docstrings
"sphinx.ext.viewcode",
"sphinx.ext.intersphinx",
"sphinx_autodoc_typehints", # 可选：显示类型注解
]
autosummary_generate = True # 自动生成 autosummary stub 页面
autodoc_typehints = "description" # 把 type hints 放到 docstring 中（可选）
# Napoleon 配置，支持 Google & NumPy 风格并可按需调整
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_param = True
napoleon_use_ivar = False
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]
# intersphinx target example (optional)
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
}
# If you use package version from your package
# try:
# from yourpackage import __version__ as package_version
# release = package_version
# except Exception:
# pass
- 准备：
docs/index.rst
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Welcome to your project's docs!
===============================
- 准备：
docs/Makefile
# Makefile for Sphinx docs
SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = _build
.PHONY: help clean html
help:
@echo "Usage: make <target>"
@echo "Targets:"
@echo " html build HTML documentation"
clean:
@rm -rf $(BUILDDIR)
html:
$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" -q
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
生成文档
- 安装依赖库
pip install -r requirements-docs.txt
- 生成模块 rst 文件
sphinx-apidoc -o docs/ app/
- 生成文档
cd docs && make html
sphinx-build -M html "." "_build" -q
Build finished. The HTML pages are in _build/html.
- 查看网页
docs/_build/html/index.html
以上便是本文的全部内容，感谢您的阅读，如遇到任何问题，欢迎在评论区留言讨论。