python sphinx(文档生成器)入门
简介
Sphinx 是一个 文档生成器 ,您也可以把它看成一种工具,它可以将一组纯文本源文件转换成各种输出格式,并且自动生成交叉引用、索引等。也就是说,如果您的目录包含一堆 reStructuredText 或 Markdown 文档,那么 Sphinx 就能生成一系列HTML文件,PDF文件(通过LaTeX),手册页等。
安装
pip install sphinx
查看是否安装成功
sphinx-build --version
显示对应的版本号即代表安装成功
sphinx-build 5.0.2
Markdown
安装markdown支撑的模块
pip install myst-parser
安装md文档相关主题
pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables
创建项目
执行如下命令,可以得到一个初始项目
sphinx-quickstart
目录结构如下:
其中
source
:文件夹下存放的时配置文件、文档源文件等, 其中最核心的则是conf.py文件和index.rst文件
- conf.py文件是整个项目的配置文件,可以配置插件、主题、项目名称、中英文等
- index.rst文件是整个项目的目录结构,相当于是主目录的意思
build
:文件夹下存放的是编译后产生的文件
make.bat
:编译所需脚本
md文档转换
设置插件
在conf.py文件中设置extensions
字段添加md文档处理
extensions = ["recommonmark"]
新建md文件
下面在source
文件夹下新建一个子文件夹叫test
, 里面存放md文档相关数据,此处新建一个test.md文档,内容如下:
## 简介
## 测试图片



在主目录中添加md文件目录
在 index.rst中修改如下:
.. toctree::
:maxdepth: 2
test/test
编译
在项目根目录下执行如下命令转为html
# 需要注意windows是bat文件
make html
sphinx-build -b html sourcedir builddir
此处就是
sphinx-build -b html source build
生成html文件
所有生成的文件都会存放在build路径下,会有两个文件夹,一个是doctrees
,还有一个是html
,
html相关会存放在html目录下。如下
注意事项
1.关于图片的引用,sphinx会自动将图片文件移动到_images文件夹下,不同文件夹下的图片都会移动到这个文件夹下,图片名称不建议使用中文名称
,会导致无法正常移动图片。
2.关于图片不同文件夹下名称相同,移动后会将同名的文件进行重命名,添加序号之类的,因此不会影响实际显示效果。
参考
python sphinx(文档生成器)入门的更多相关文章
- python sphinx 文档自动生成方法
## sphinx 生成开发文档#### 配置 1. 运行如下命令,即可生成 conf.py index.rst Makefile 三个文件: `sphinx-quickstart` 2. conf. ...
- MkDocs项目文档生成器
简介 安装 我的配置 Chocolatey 简介 - Windows的包管理器 官方网址 安装 注意事项 Python 简介 安装 Pip 简介-Python的包管理器 升级 MkDocs的安装 使用 ...
- sphinx文档
Navigation index modules | Sphinx主页 | 文档 » 下载 目前版本: 1.2 获得 Sphinx 从 Python Package Index, 或者使用如下命令安装 ...
- Sandcastle帮助文档生成器使用介绍
一.软件介绍 Sandcastle是一个管理类库的文档编译器,是用于编译发布组件(Assembly)信息的一个工具,这个工具通过反射和Xslt技术,可以从dll文件及其xml注释(命令行编 ...
- 如何在命令行模式下查看Python帮助文档---dir、help、__doc__
如何在命令行模式下查看Python帮助文档---dir.help.__doc__ 1.dir函数式可以查看对象的属性,使用方法很简单,举str类型为例,在Python命令窗口输入 dir(str) 即 ...
- api的mock开源工具;api文档生成器;api的mock工具;阿里系;其他开源
django-rest-framework,即drf的api文档,包括自带的文档和其他三方文档,比如swagger.DRF Docs等 https://www.django-rest-framewor ...
- python统计文档中词频
python统计文档中词频的小程序 python版本2.7 效果如下: 程序如下,测试文件与完整程序在我的github中 #统计空格数与单词数 本函数只返回了空格数 需要的可以自己返回多个值 def ...
- PHP文档生成器(PHPDoc)的基本用法
目录 PHP文档生成器(PHPDoc)的基本用法 PHPDoc概述 安装 PHPDoc注释规范 页面级别的注释 代码级别的注释 生成API文档 额外软件 PHP文档生成器(PHPDoc)的基本用法 P ...
- 在命令行模式下查看Python帮助文档---dir、help、__doc__
在命令行模式下查看Python帮助文档---dir.help.__doc__ 1.dir函数式可以查看对象的属性,使用方法很简单,举str类型为例,在Python命令窗口输入 dir(str) 即 ...
随机推荐
- ansible中的playbook脚本的介绍与使用
playbook的数据结构,遵循yaml 后缀名为yaml或者yml,这两个后缀名没有区别 字典{key:value} 列表[]或者- - alex - wusir - yantao - yuchao ...
- Next.js 在 Serverless 中从踩坑到破茧重生
作者 杨苏博,偏后端的全栈开发,目前负责腾云扣钉的 Cloud Studio 产品.在团队中负责接技术架构设计与 Review.Cloud Studio 编辑器内核设计与开发.部分核心插件设计与开发: ...
- 【多线程】线程强制执行 join()
线程强制执行 join() Join合并线程,待此线程执行完成后,再执行其他线程,其他线程阻塞 : 可以想象成插队. 代码示例: /** * @Description 测试join方法 * @Auth ...
- Git 不识别文件名字母大小写变化
问题 今天为一个项目撰写持续构建计划,撰写 Jenkinsfile 之后进行构建时报错: [2022-05-23 16:54:21] unable to prepare context: unable ...
- TyepScript学习
前提 JS缺陷 (1)变量频繁变换类型,类型不明确难以维护 TS定义 (1)定义 以JavaScript为基础构建的语音,一个JavaScript的超集,扩展js添加了类型, 可以在任何支持js的平台 ...
- sqlserver 插入 更新 删除 语句中的 output子句
官方文档镇楼: https://docs.microsoft.com/zh-cn/previous-versions/sql/sql-server-2008/ms177564(v=sql.100) 从 ...
- vsftp 详解
1.默认配置: 1>允许匿名用户和本地用户登陆. anonymous_enable=YES local_enable=YES2>匿名用户使用的登陆名为ftp或anonymo ...
- mybatis if判断等于某个字符串
这种写法是错误的:在OGNL的表达式中,'true'会被解析成字符,因为java是强类型的 <if test="flag=='true' "> AND ho.id = ...
- csv.reader(f)和f.readlines()、追加数据
假如某个文档f中存储如下内容: 你好,中国. 1,2,3,4 共两行内容. 当你使用csv.reader(f),则会存储为如下形式: [['你','好','中','国'] ['1','2','3',' ...
- 测试平台系列(97) 完善执行case部分
大家好~我是米洛! 我正在从0到1打造一个开源的接口测试平台, 也在编写一套与之对应的教程,希望大家多多支持. 欢迎关注我的公众号米洛的测开日记,获取最新文章教程! 回顾 上一节我们讨论了怎么结束一个 ...