简介

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文档,内容如下:

## 简介
## 测试图片 ![avatar](../images/test/test.gif)
![avatar](../images/test2/test.gif)
![avatar](../images/test2/test.jpg)

在主目录中添加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.关于图片不同文件夹下名称相同,移动后会将同名的文件进行重命名,添加序号之类的,因此不会影响实际显示效果。

参考

sphinx官方文档

python sphinx(文档生成器)入门的更多相关文章

  1. python sphinx 文档自动生成方法

    ## sphinx 生成开发文档#### 配置 1. 运行如下命令,即可生成 conf.py index.rst Makefile 三个文件: `sphinx-quickstart` 2. conf. ...

  2. MkDocs项目文档生成器

    简介 安装 我的配置 Chocolatey 简介 - Windows的包管理器 官方网址 安装 注意事项 Python 简介 安装 Pip 简介-Python的包管理器 升级 MkDocs的安装 使用 ...

  3. sphinx文档

    Navigation index modules | Sphinx主页 | 文档 » 下载 目前版本: 1.2 获得 Sphinx 从 Python Package Index, 或者使用如下命令安装 ...

  4. Sandcastle帮助文档生成器使用介绍

    一.软件介绍       Sandcastle是一个管理类库的文档编译器,是用于编译发布组件(Assembly)信息的一个工具,这个工具通过反射和Xslt技术,可以从dll文件及其xml注释(命令行编 ...

  5. 如何在命令行模式下查看Python帮助文档---dir、help、__doc__

    如何在命令行模式下查看Python帮助文档---dir.help.__doc__ 1.dir函数式可以查看对象的属性,使用方法很简单,举str类型为例,在Python命令窗口输入 dir(str) 即 ...

  6. api的mock开源工具;api文档生成器;api的mock工具;阿里系;其他开源

    django-rest-framework,即drf的api文档,包括自带的文档和其他三方文档,比如swagger.DRF Docs等 https://www.django-rest-framewor ...

  7. python统计文档中词频

    python统计文档中词频的小程序 python版本2.7 效果如下: 程序如下,测试文件与完整程序在我的github中 #统计空格数与单词数 本函数只返回了空格数 需要的可以自己返回多个值 def ...

  8. PHP文档生成器(PHPDoc)的基本用法

    目录 PHP文档生成器(PHPDoc)的基本用法 PHPDoc概述 安装 PHPDoc注释规范 页面级别的注释 代码级别的注释 生成API文档 额外软件 PHP文档生成器(PHPDoc)的基本用法 P ...

  9. 在命令行模式下查看Python帮助文档---dir、help、__doc__

    在命令行模式下查看Python帮助文档---dir.help.__doc__   1.dir函数式可以查看对象的属性,使用方法很简单,举str类型为例,在Python命令窗口输入 dir(str) 即 ...

随机推荐

  1. ansible中的playbook脚本的介绍与使用

    playbook的数据结构,遵循yaml 后缀名为yaml或者yml,这两个后缀名没有区别 字典{key:value} 列表[]或者- - alex - wusir - yantao - yuchao ...

  2. Next.js 在 Serverless 中从踩坑到破茧重生

    作者 杨苏博,偏后端的全栈开发,目前负责腾云扣钉的 Cloud Studio 产品.在团队中负责接技术架构设计与 Review.Cloud Studio 编辑器内核设计与开发.部分核心插件设计与开发: ...

  3. 【多线程】线程强制执行 join()

    线程强制执行 join() Join合并线程,待此线程执行完成后,再执行其他线程,其他线程阻塞 : 可以想象成插队. 代码示例: /** * @Description 测试join方法 * @Auth ...

  4. Git 不识别文件名字母大小写变化

    问题 今天为一个项目撰写持续构建计划,撰写 Jenkinsfile 之后进行构建时报错: [2022-05-23 16:54:21] unable to prepare context: unable ...

  5. TyepScript学习

    前提 JS缺陷 (1)变量频繁变换类型,类型不明确难以维护 TS定义 (1)定义 以JavaScript为基础构建的语音,一个JavaScript的超集,扩展js添加了类型, 可以在任何支持js的平台 ...

  6. sqlserver 插入 更新 删除 语句中的 output子句

    官方文档镇楼: https://docs.microsoft.com/zh-cn/previous-versions/sql/sql-server-2008/ms177564(v=sql.100) 从 ...

  7. vsftp 详解

    1.默认配置: 1>允许匿名用户和本地用户登陆.     anonymous_enable=YES     local_enable=YES2>匿名用户使用的登陆名为ftp或anonymo ...

  8. mybatis if判断等于某个字符串

    这种写法是错误的:在OGNL的表达式中,'true'会被解析成字符,因为java是强类型的 <if test="flag=='true' "> AND ho.id = ...

  9. csv.reader(f)和f.readlines()、追加数据

    假如某个文档f中存储如下内容: 你好,中国. 1,2,3,4 共两行内容. 当你使用csv.reader(f),则会存储为如下形式: [['你','好','中','国'] ['1','2','3',' ...

  10. 测试平台系列(97) 完善执行case部分

    大家好~我是米洛! 我正在从0到1打造一个开源的接口测试平台, 也在编写一套与之对应的教程,希望大家多多支持. 欢迎关注我的公众号米洛的测开日记,获取最新文章教程! 回顾 上一节我们讨论了怎么结束一个 ...