使用sphinx+reStructuredText制作文档
文章目录
- spinx简介
- rst简介
- 环境准备
- 安装python
- 安装sphinx和restructuredtext-line
- 安装文本编辑器vscode
- 安装python扩展
- 安装rst扩展
- 部署sphinx
- 创建并打开工程目录
- 创建sphinx工程
- 开始编写rst文档
- 第一次打开rst文件
- 帮助文档
- 自定义sphinx主题
- 生成html文档
- 预览html文档
- 发布
- 错误排查
- vscode中看不到预览
- 参考
spinx简介
Sphinx 是一种文档工具，它可以让人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是由Sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持。Sphinx还在继续开发。下面列出了其良好特性,这些特性在Python官方文档中均有体现:
- 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本
- 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
- 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
- 美观的自动索引: 可自动生成美观的模块索引
- 精确的语法高亮: 基于 Pygments 自动生成语法高亮
- 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等
rst简介
reStructuredText，译为"重新构建的文本"，也被简称为RST或reST。
基于该语言写的文件.rst文件是一种纯文本文件。
rst是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。
Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。
rst文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。
环境准备
安装python
安装sphinx和restructuredtext-line
打开终端，输入pip install sphinx
pip install sphinx
pip install restructuredtext-lint
安装文本编辑器vscode
安装python扩展
安装一个受支持的pyhton版本
安装python扩展
开始使用
安装rst扩展
view -> extensions，输入restructuredText，下载完成后重启vscode
部署sphinx
创建并打开工程目录
创建一个工程目录d:/mydownload/sphinxtest
使用vscode打开该目录，file -> open folder
创建sphinx工程
- 打开cmd终端，使用cd命令进入工程目录；或者在vscode中打开终端，
view->terminal，这样打开就是在工程目录下的。下面以cmd终端为例：
Microsoft Windows [版本 10.0.18362.778]
(c) 2019 Microsoft Corporation。保留所有权利。
C:\Users\loki0>cd d:/mydownload/sphinxtest
C:\Users\loki0>d:
d:\mydownload\sphinxtest>
- 输入
sphinx-quickstart
d:\mydownload\sphinxtest>sphinx-quickstart
sphinx-quickstart命令官方详细文档
若使用虚拟环境，则进入虚拟化境中输入该命令。
- 输入y，分离source和build目录
Welcome to the Sphinx 3.0.2 quickstart utility.Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).Selected root path: .You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
- 输入工程名称，作者，工程发行版本
The project name will occur in several places in the built documentation.
> Project name: test
> Author name(s): loki
> Project release []: Rev1
- 选择工程语言，这里选择简体中文zh_CN，关于支持的语言，可打开终端中提示的链接，下面的链接可能在将来失效。
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN
- 工程创建完成
Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.Finished: An initial directory structure has been created.You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
开始编写rst文档
第一次打开rst文件
打开index.rst
第一次打开rst文件，会有如下提示，本教程用的是sphinx，所以选择sphinx。
如要修改该设置，参考下图：
单击预览按钮，即可看到预览界面
帮助文档
工程已经创建好了，接下来就可以开始编写rst文档了，rst的语法不在这里详细讲解，请参阅以下内容，或者自行搜索资料：
rst快速入门
sphinx对rst的英文帮助文档
sphinx对rst的中文帮助文档
本文的参考文章的作者的学习笔记（推荐）
自定义sphinx主题
官方主题参考
sphinx_rtd_theme是一个比较流行的主题，rtd即Read the Docs，是一个在线文档托管服务。
打开cmd终端，输入以下命令，安装sphinx_rth_theme主题：
pip install sphinx_rtd_theme
安装完成后，修改conf.py文件：
html_theme = 'sphinx_rtd_theme'
生成html文档
打开cmd终端，进入工程目录，输入以下命令，生成html文档
d:\mydownload\sphinxtest>.\make clean
d:\mydownload\sphinxtest>.\make html
注意：这里生成的是html，也可以生成dirhtml,singlehtml,epub,devhelp,latex,man,texinfo,text等多种格式
注意：如果用的是虚拟环境，则要激活虚拟环境后再执行命令。
注意：在vscode中强制使用.\make代替make，在cmd终端两种写法皆可，.\make是比较严谨的相对路径。
更多内容可参考sphinx官方make命令详解
预览html文档
进入./build/html，打开index.html，享受第一次的喜悦。
也可以使用web代理服务器，代理这些html文档
发布
发布的方式比较多。简单点可以把html目录挂到iis，或者apache，httpd对应的网页目录即可。
这里使用redthedoc。
错误排查
vscode中看不到预览
排查思路
- 检查python路径，如果使用虚拟路径的需要关注下。
- 是否安装了sphinx工具
- conf.py文件的位置是否正确
- 查看预览错误信息
vscode会创建.vscode的目录，存放settings.json文件， python多使用虚拟环境，要设置虚拟环境路径，可参考以下配置修改settings.json：
Linux：
{"restructuredtext.confPath": "${workspaceFolder}",
"python.pythonPath":"/Users/dxm/Envs/sphinx/bin/python"
}
windows：
{"restructuredtext.styles": [],// "python.pythonPath": "C:\\Users\\loki0\\AppData\\Local\\Programs\\Python\\Python38\\python.exe","python.pythonPath": "D:/pyvenv/sphinx/Scripts/python.exe","restructuredtext.confPath": "${workspaceFolder}\\source"
}
path是所用环境的python.exe的完整路径，注意Linux和windows的区别。
若vscode报错，注意检查是否用","断句。
参考
sphinx+reStructuredText制作文档
sphinx中文帮助文档
sphinx英文帮助文档
使用sphinx+reStructuredText制作文档相关推荐
- 使用计算机制作文档的方法是,2.2使用word 2003制作文档.doc
2.2 使用Word2003制作文档 教 学 设 计 表 学科________授课年级________学校________教师姓名________课题名称使用Word2003制作文档计划 学时4学习内 ...
- 虚幻5简单第三人称游戏制作文档
虚幻5简单第三人称游戏制作文档 基本需求 最后成果与ue5引擎第三人称初始化后的内容类似(但要从空白项目做起) 基础创建 登录到 Epic Games启动程序,通过 新建(New)>游戏(Gam ...
- IGEM WIKI 制作文档
IGEM WIKI 一.页面以及样式代码的上传 1.1 网页的上传 输入一个曾经没有编辑过的URL 格式为https://2020.igem.org/Team:Team_Name/NewPage 会进 ...
- am335x sd卡分区制作文档
制作一张SD启动卡,可以有两种选择,第一,利用TI-SDK的脚本来制作,该脚本功能较多,可以制作2分区的也可以制作3分区的启动卡,而且写入的相关启动文件比如MLO.u-boot.img.根文件系统(包 ...
- 使用 Sphinx 撰写技术文档并生成 PDF 总结
这几天准备编排部分翻译的书籍和文档,找了好些工具,最终定格在 Sphinx 上,并基于 ReadTheDocs 提供的 SaaS 服务进行分发和分享.本篇博客是对整个过程的一次记录和总结. 项目代码: ...
- Windows下配置sphinx+reStructuredText详解
最近有朋友想在windows下做个人笔记,没有找到顺手的工具,问我有什么好的工具推荐.正好前两天在网上看到一款做文档的利器sphinx+reStructText,当时在ubuntu下搭了下环境试了试, ...
- 如何修改DynEd的学生记录服务器,DynEd教师管理端操作文档..docx
DynEd教师管理端操作文档. DynEd教师管理端Records Manager操作文档DynEd教学理念语言是一种技能传统的英语教学太过注重读写,而疏于听说能力的发展.学生花费了大量的时间来背单词 ...
- mallplus多商户商城全流程 操作文档
下载地址 https://gitee.com/catshen/zscat_sw 用户端 http://www.yjlive.cn:8082/#/ 商户端 http://www.yjlive.cn:80 ...
- 必备：产品经理工作文档大全
产品经理(英文:Product manager,缩写:PM)也称产品企划,是指在公司中针对某项或某类的产品进行规划和管理的人员,主要负责产品的研发.制造.营销.渠道等工作. 产品经理是很难定义的一个角 ...
- sphinx 编码 php文档,用Sphinx编写技术文档
用Sphinx编写技术文档 大家会发现,如果一个项目主要是用Python写的,其文档都很类似,比如:Python在线的HTML官方手册.这些项目的文档都来源于一个很不错的项目:Sphinx.这个Sph ...
最新文章
- 关于做Android+J2ee系统集成开发的一点心得
- 【 C 】作用域、链接属性、存储类型、static 关键字简介及总结
- HDU 2189 悼念512汶川大地震遇难同胞——来生一起走
- ef 多个左联接查询_.NET 云原生架构师训练营（模块二 基础巩固 EF Core 查询）--学习笔记...
- django Rest Framework----认证/访问权限控制/访问频率限制 执行流程 Authentication/Permissions/Throttling 源码分析...
- ios h5 出现的问题
- Java匹马行天下之学编程的起点——走进编程的殿堂
- [权威指南]学习笔记——第3章 创建、更新和删除文档
- jenkins教程菜鸟_jenkins新手入门教程
- 50个Windows自带软件的免费替代品
- Unity技术分享之Mac环境下dll反编译
- 软件架构师应具备的十大特点
- ZT世界第九大奇迹--北京西直门立交桥〔爆笑〕
- C++ Bulider6.0下string类型问题
- 与计算机学男生谈恋爱,和什么专业男生谈恋爱比较惨？
- 【Python学习】pandas 删除重复行
- Tair ldb（leveldb存储引擎）实现介绍
- 拦截QT关闭窗口的CloseEvent()解析
- axis2 jax-ws_Axis2 WS-Security基础知识
- 伽马变换的原理以及python实现