Sphinx初尝
我们经常可以看到这种的doc文档,简洁大方.作为阅读可谓看着是赏心悦目
那么我能不能自己做一个这样的doc呢,我想是可以的,大家跟着我试试看!
https://robomaster-dev.readthedocs.io/zh_CN/latest/python_sdk/beginner_multi_robot.html
最近一位朋友想做个大疆的EP车,我提供一些建议,在看Dji的SDK,我就顺手拿这个来做示范了.
https://iridescent.ink/HowToMakeDocs/Basic/Sphinx.html
https://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html
我们实现上述的目的,使用的是Sphinx:
Sphinx 是一种文档工具,它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是由Sphinx生成的, 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的,它采用reStructuredText! Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:
丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages(man 文档), 纯文本
完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
美观的自动索引: 可自动生成美观的模块索引
精确的语法高亮: 基于 Pygments 自动生成语法高亮
开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等
Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析,转换等多种工具.
此为最新的Python文档
https://docs.python.org/zh-cn/3/
首先创建一个文件夹,为了避免污染环境
先看看目录
在pip
是否分离source和build目录(输入y,选择分离,方便管理)
欢迎使用Sphinx 3.3.0快速入门实用程序。
请输入以下设置的值(只需按Enter
接受默认值(如果在括号中给出)。
选定的根路径:。
您有两个选择来放置Sphinx输出的构建目录。
您可以在根路径中使用目录“ _build”,也可以单独使用
根路径中的“源”和“构建”目录。
有一些提示,自己摁
项目名称将在生成的文档中的多个位置出现。
>项目名称:yunswj
>作者姓名:yunswj
>项目发布[]:0.1
如果要用英语以外的其他语言写文件,
您可以在此处通过语言代码选择一种语言。狮身人面像
将其生成的文本翻译成该语言。
有关受支持代码的列表,请参见
https://www.sphinx-doc.org/zh-CN/master/usage/configuration.html#confval-language。
>项目语言[zh]:
创建文件C:\ Users \ yunswj \ Desktop \ Sphinx \ source \ conf.py。
创建文件C:\ Users \ yunswj \ Desktop \ Sphinx \ source \ index.rst。
创建文件C:\ Users \ yunswj \ Desktop \ Sphinx \ Makefile。
创建文件C:\ Users \ yunswj \ Desktop \ Sphinx \ make.bat。
完成:初始目录结构已创建。
现在,您应该填充主文件C:\ Users \ yunswj \ Desktop \ Sphinx \ source \ index.rst并创建其他文档
源文件。使用Makefile构建文档,如下所示:
使建设者
其中“构建器”是受支持的构建器之一,例如html,latex或linkcheck。
项目名字
编辑者姓名
文档的版本号
项目语言,我这边选择默认了.回车就好
会生成这些文件.
这是生成的结构
build:用来存放通过make html生成文档网页文件的目录
source:存放用于生成文档的源文件
conf.py: Sphinx的配置文件
index.rst: 主文档
config.py的详细信息
https://www.sphinx-doc.org/en/master/usage/configuration.html
这个是配置文件可以看到是和我创建文件的时候的内容相符
https://www.sphinx-doc.org/en/master/usage/configuration.html
project
记录的项目名称。
author
文档的作者姓名。默认值为
'unknown'
。
copyright
风格的版权声明。
'2008, Author Name'
version
主要项目版本,用于替代
|version|
。例如,对于Python文档,这可能类似于2.6
。release
完整的项目版本,用于替换
|release|
HTML模板,例如在HTML模板中。例如,对于Python文档,这可能类似于2.6.0rc1
。
显示错误,很智能的提醒我用.\这种语法
可以输出的类型,有一些并不可以输出.缺少东西
.\make 文件类型
运行Sphinx v3.3.0
制作输出目录...完成
建立[mo]:过时的0个po文件的目标
建立[html]:过时的1个源文件的目标
更新环境:[新配置]添加了1个,更改了0个,删除了0个
阅读来源... [100%]索引
寻找过时的档案...找不到
酸洗环境...完成
检查一致性...完成
正在准备文件...完成
写输出... [100%]索引
生成索引... genindex完成
写其他页面...搜索完成
复制静态文件...完成
复制多余的文件...完成
用英语(代码:en)倾销搜索索引...完成
倾销对象清单...完成
建立成功。
HTML页面位于build \ html中。
编译过后的目录是这样的
里面有三个html文件,都打开看看
以上是打开的三个网页文档
那我写完就想自动预览文档,咋办?当然可以啦
这个是我的浏览器的位置,你如果也是chrome,可以直接复制我的地址
C:\Program Files\Google\Chrome\Application
把浏览器的目录加环境变量,自己找
在:end和popd中间加代码
:end
REM ----------------------------------------------
REM Added by Yunswj - Auto open build file
REM ----------------------------------------------
if "%1" == "html" (
chrome build/html/index.html
)
popd
改成这样
第一次报错
powershell还是不可以
用cmd打开正常,这个powershell其实更shell一些
此时,我们要看一眼托管以及用他家的主题
https://readthedocs.org/
我用Github登录了
就是一个托管平台,巴适的很
https://readthedocs.org/projects/yunswj-demo/
这些指令是生成自己的doc
这个是默认生成的doc
这个是源代码
云服务器编译,有点好用
详细设置
可以导入自己的文档(在线)
可以看到有很多详细的选项
https://readthedocs.org/dashboard/import/manual/?
可以这样用地址导入
https://github.com/readthedocs/template
pip install sphinx_rtd_theme
这里我也不托管,先搞一手主题
安装
成功
# for using Read the Docs theme
import sphinx_rtd_theme
# html_theme = 'sphinxdoc'
html_theme = 'sphinx_rtd_theme'
#html_theme_path = []
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
重新编译没有变化
为了可以自动预览,用cmd
还是主题未变,之后在解决
支持markdown文件、更改文档主题
Spinx本身不支持.md文件生成文档,需要我们使用第三方库recommonmark进行转换。首先分别运行下列命令安装recommonmark与sphinx_rtd_theme库。
pip install recommonmark
pip install sphinx_rtd_theme
安装好,在conf.py中修改下列两个配置:
source_suffix = ['.rst', '.md', '.MD']
html_theme = 'sphinx_rtd_theme'
并新增:
source_parsers = {
'.md': CommonMarkParser,
'.MD': CommonMarkParser,
}
https://sphinx-doc-zh.readthedocs.io/en/latest/tutorial.html
这篇已经很多了,下篇继续写