Sphinx是一个工具,可以轻松创建智能和漂亮的文档,他与Python自带的pydoc是同一类产品,但比pydoc更加优秀,还有很多主题可以选择,平时在开发过程中,我们看到的第三方包的文档,基本上都是用该模块自动生成的,今天我就带大家手把手将其集成到django项目当中,使其为我们的django项目自动生成文档,今天小编就来聊一聊关于django开发规范?接下来我们就一起去研究一下吧!

django开发规范(为项目自动生成文档)

django开发规范

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

运行这个命令后,终端会弹出创建基本目录和配置布局的一系列问题,内容如下:

├── 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目录中文件用途如下:

-- 编译生成的最终文档静态文件存放目录

-- 方便的脚本,用于简化一些编译操作命令,例如渲染内容。

-- 保存 Sphinx 项目配置的 Python 脚本。它包含您指定的项目名称和版本,以及一些额外的配置键。

-- 项目的根文档,用作欢迎页面,即首页,并包含"目录树"。

做完以上工作之后,他还不能自动将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/就可以访问到我们的文档!

为文档更换主题

主题站点:https://sphinx-themes.org/

这个站点为sphinx提供了很多风格的主题皮肤,我们可以去挑选适合自己的通过pip命令安装即可,安装之后只需要修改source目录中的conf.py文件中的html_name配置项的名称为对应的主题名称即可完成换肤!

欢迎大家关注学习,一起进步,笔者专注django相关开发,对django有深入研究,可一起学习探讨,并且承接django相关项目的开发任务!

,