编程语言
首页 > 编程语言> > Python:文档工具Sphinx教程001

Python:文档工具Sphinx教程001

作者:互联网

简介:Sphinx 是一种文档工具,它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发。新版的Python文档 就是由Sphinx生成的, 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持。

优势特性:

  1. 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual
    pages(man 文档), 纯文本
  2. 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
  3. 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
  4. 美观的自动索引: 可自动生成美观的模块索引
  5. 精确的语法高亮: 基于 Pygments 自动生成语法高亮
  6. 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

安装:

pip install -U sphinx

创建sphinx项目:

sphinx-quickstart

创建后依次需要填的信息:
1、项目名称:任意
2、作者:任意
3、版本:任意
4、语言:zh_CN 中文

图片

各个文件的作用:

build:生成的文件的输出目录

source: 存放文档源文件

_static:静态文件目录,比如图片等

_templates:模板目录

conf.py:进行 Sphinx 的配置,如主题配置等

index.rst:文档项目起始文件,用于配置文档的显示结构

cmd.bat:这是自己加的脚本文件(里面的内容是‘cmd.exe’),用于快捷的打开windows的命令行

make.bat:Windows 命令行中编译用的脚本

Makefile:编译脚本,make 命令编译时使用

编译脚本:

make html

打开build\html文件:
图片

安装autobuild工具:

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild

编译指令进行编译:

sphinx-autobuild source build/html

通过浏览器查看效果:http://127.0.0.1:8000/
图片

自此,Sphinx文档工具快速搭建使用完成阶段一。

微信公众号:玩转测试开发
欢迎关注,共同进步,谢谢!

在这里插入图片描述

标签:Sphinx,autobuild,Python,编译,001,文档,sphinx
来源: https://blog.csdn.net/hzblucky1314/article/details/122508711