Sphinx是一个工具，可以轻松创建智能和漂亮的文档，他与Python自带的pydoc是同一类产品，但比pydoc更加优秀，还有很多主题可以选择，平时在开发过程中，我们看到的第三方包的文档，基本上都是用该模块自动生成的，今天我就带大家手把手将其集成到django项目当中，使其为我们的django项目自动生成文档！
创建一个django的Demo项目
# 创建虚拟环境
python3 -m venv venv
# 激活虚拟环境
venv\Scripts\activate ## windowns激活
source venv/bin/activate ## linux激活
# 安装django
pip3 install django
# 创建django项目
django-admin startproject mysite .
# 创建一个demo的app
python3 manage.py startapp demo经过以上命令我们已经成功创建了一个基础的django项目框架，之后我们就需要通过pip命令来安装Sphinx，来正式进入我们今天的主题！
pip命令安装Sphinx
# 安装sphinx
pip3 install sphinx
# 查看版本号验证是否安装成功
sphinx-build --version
# 返回版本号信息，说明安装成功
sphinx-build 4.4.0 创建文档布局
sphinx-quickstart docs
运行这个命令后，终端会弹出创建基本目录和配置布局的一系列问题，内容如下：
- > Separate source and build directories (y/n) [n]：y 是否分离源和构建目录输入y
- > Project name：mysite 项目名称
- > Author name(s)：name 文档作者名称
- > Project release []：1.0 文档版本号
- > Project language [en]： 文档语言，默认留空，为英文
├── docs
│?? ├── build
│?? │?? └── doctrees
│?? ├── make.bat
│?? ├── Makefile
│?? └── source
│?? ├── conf.py
│?? ├── index.rst
│?? ├── _static
│?? └── _templates
├── demo
│?? ├── admin.py
│?? ├── apps.py
│?? ├── __init__.py
│?? ├── migrations
│?? ├── models.py
│?? ├── static
│?? ├── templates
│?? ├── tests.py
│?? ├── urls.py
│?? └── views.py
├── mysite
│?? ├── asgi.py
│?? ├── __init__.py
│?? ├── settings.py
│?? ├── urls.py
│?? └── wsgi.py
├── db.sqlite3
└── manage.py 运营完以上命令之后，我们将得到如上所示的一个目录结构，docs则是我们的文档目录，docs目录中文件用途如下：
- build/
-- 编译生成的最终文档静态文件存放目录
- make.bat和Makefile
-- 方便的脚本，用于简化一些编译操作命令，例如渲染内容。
- source/conf.py
-- 保存 Sphinx 项目配置的 Python 脚本。它包含您指定的项目名称和版本，以及一些额外的配置键。
- source/index.rst
-- 项目的根文档，用作欢迎页面，即首页，并包含"目录树"。
做完以上工作之后，他还不能自动将django项目中的注释内容提取到文档当中，因为他还识别不到我们的django项目及目录，需要在source/conf.py文件中进一步配置！
...
import os
import sys
# 引入django,使其可以独立运行
import django
# 找到项目的根目录
sys.path.insert(0, os.path.abspath('../../'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'
# 启动django命令，这个很重要
django.setup()
# -- Project information -----------------------------------------------------
project = 'mysite'
copyright = '2022, name'
author = 'name'
...以上内容便是source/conf.py中新增的配置，还需要确保在其内部的extensions配置项中配置如下代码：
extensions = [
'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc'
]接下来就可以生成rst文件了，运行以下命令
sphinx-apidoc -o docs/source/mysite ../mysite-o后边跟随的路径是我们生成rst的保存目录，一般都存放在docs/source中，至于再是否增加子目录视情况而定； 空格后跟随的 ../mysite则是我们需要提取的目录，这里的路径如果用相对路径不熟练的话可以用绝对路径！
至此，我们可以看到docs/source目录中多出来一个mysite的目录，并且生成了相关的rst文件，这些rst文件中的内容可以进一步手动定义，具体可以参考官方文档！
编译生成html文档
这里有两种方法，假如我们目前在manage.py文件的同级目录，可以运行如下命令
sphinx-build -b html docs/source/ docs/build/html这个命令可以帮我们生成静态的html文件，并编译存放到docs/build/html目录中，-b 后边跟随的html就是编译的文档格式， 当然还可以编译成好几种格式，但是一般我们django的话都编译成html，因为文档我们还要部署到线上！
另外一种简便的方法就是进入docs目录（cd docs），直接运行make html即可！
走到这一步build目录中就生成了一个html目录，这就是我们要访问的文档目录！
但是，如何才能让这个文档在线上可以访问呢？这就需要在django项目中为文档目录配置url，让其可以访问！
配置docs访问地址
在项目的配置文件settings.py中添加如下代码，路径为：mysite/settings.py
# 集成文档
DOCS_URL = '/docs/' # url
DOCS_ROOT = BASE_DIR / 'docs/build/html' # 文档路径在项目的urls.py中增加以下配置， 路径为：mysite/urls.py
from django.contrib import admin
from django.urls import path
# 新增的
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
path('admin/', admin.site.urls),
# 加入docs目录
] + static(settings.DOCS_URL , document_root=settings.DOCS_ROOT) 至此，启动我们的项目runserver之后，访问127.0.0.1:8000/docs/就可以访问到我们的文档！
为文档更换主题
这个站点为sphinx提供了很多风格的主题皮肤，我们可以去挑选适合自己的通过pip命令安装即可，安装之后只需要修改source目录中的conf.py文件中的html_name配置项的名称为对应的主题名称即可完成换肤！
欢迎大家关注学习，一起进步，笔者专注django相关开发，对django有深入研究，可一起学习探讨，并且承接django相关项目的开发任务！