django集成Sphinx,为项目自动生成文档
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 staticurlpatterns = [path('admin/', admin.site.urls),
# 加入docs目录
] + static(settings.DOCS_URL , document_root=settings.DOCS_ROOT)
至此,启动我们的项目runserver之后,访问127.0.0.1:8000/docs/就可以访问到我们的文档!
为文档更换主题
主题站点:Sphinx Themes Gallery
这个站点为sphinx提供了很多风格的主题皮肤,我们可以去挑选适合自己的通过pip命令安装即可,安装之后只需要修改source目录中的conf.py文件中的html_name配置项的名称为对应的主题名称即可完成换肤!
欢迎大家关注学习,一起进步,笔者专注django相关开发,对django有深入研究,可一起学习探讨,并且承接django相关项目的开发任务!
django集成Sphinx,为项目自动生成文档相关推荐
- Matlab联合wps的API生成文档,让API自动生成文档
原标题:让API自动生成文档 程序员最苦恼的事情莫过于写文档.由于业务口径频繁变更,因此很多接口也会频繁变更,频繁变更导致文档的维护是一件相当费时的事情,当优先级更高的事情袭来,更新文档反到成了次要工 ...
- Java使用smart-doc自动生成文档
作为后端开发,写接口文档一直是一个很头痛的问题,今天推荐一个开源工具smart-doc,这个工具基于java原生的注释生成api文档,无需大量的注解配合使用. 官方地址:https://gitee.c ...
- spring boot rest接口自动生成文档(包含swagger)--gradle 下的配置
之前写过一篇文章:spring boot rest接口自动生成文档(包含swagger),这个使用的是maven作为依赖管理工具,现在,让我们体验一下gradle在spring boot项目中如何配置 ...
- Objective-C自动生成文档工具:appledoc
作者 iOS_小松哥 关注 2016.12.13 15:47* 字数 919 阅读 727评论 10喜欢 35 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective-C自动生成文 ...
- Objective-C 自动生成文档工具:appledoc
来源:iOS_小松哥 www.jianshu.com/p/fd4d8d6b6177 如有好文章投稿,请点击 → 这里了解详情 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective ...
- docwizard c++程序文档自动生成工具_如何开发一个基于 TypeScript 的工具库并自动生成文档
为什么用 TypeScript? TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any ...
- java接口废弃注释_Spring Boot如何让Web API自动生成文档,并解决swagger-annotations的API注解description属性废弃的问题...
前后端分离的系统架构中,前端开发人员需要查看后端WEB API的文档来进行开发.采用后端API文档自动生成的方式,可以大幅提高开发效率.swagger是一个被广泛使用的文档自动生成工具,可以与多种编程 ...
- MQL5 代码自动生成文档
1. 简介 大多数 Java 代码编写者熟悉可通过 JavaDocs 创建的自动生成文档.其思路是以一种半结构化的方式向代码添加注释,然后可以将这些注释提取到易于导航的帮助文件. C++ 世界也有若干 ...
- spring boot rest接口自动生成文档(包含swagger)
spring boot rest接口自动生成文档(包含swagger) 写接口免不了写接口文档,但是当文档与代码分开独立演进的时候,会发生很多不同步的问题. 接口描述与代码同 ...
最新文章
- python接口自动化5-Json数据处理
- Filling Shapes
- Redis学习-sorted set数据类型
- jquery+bootstrap实现tab切换, 每次切换时都请求数据, 点击提交分别向不同的地址提交数据...
- Java中的三目运算符可能出现的问题
- Redis——学习之路一(初识redis)
- java 读取project_java project 和 java web project 获取路径问题
- qml c++函数 slot_浅析Qt(C++),QML与HTML之间的交互
- 实体属性变更历史记录框架(三)-变更历史记录从此无忧
- Ubuntu 10.04中配置ip地址
- SQL 基础教程 (第2版)
- cookie httponly ajax,为什么jquery的.ajax()方法没有发送我的会话cookie?
- 原生js监听滚动条_JS原生监听滚动条
- 大数据热词科普(三)
- 【设计模式】迪米特法则
- 下拉列表(select标签)
- Android中的验证码输入框
- 企业增长过程中的「伪命题」
- jsMath对象中的三角函数
- STM32定时器中断时间计算
热门文章
- CTF Series Forensics
- Go语言开发学习笔记(持续更新中)
- 【Docker学习笔记 三】Docker常用容器安装及图形化管理工具
- dvsdk_4_00_00_22_dm3730 Makefile内容
- pve万兆网卡驱动_PVE+lede+DSM网卡硬盘直通+win10
- Ali-Perseus(擎天):统一深度学习分布式通信框架 [弹性人工智能]
- JAVA出现警告无法读取 AppletViewer 属性文件的解决方法
- Centos 7 虚拟机安装 jenkins
- matlab怎样编程形成软件_Matlab编程笔记之GUI程序转exe
- 【MES】MES的另一视角