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.htmlproject- 记录的项目名称。
author- 文档的作者姓名。默认值为
'unknown'。 copyright- 风格的版权声明。
'2008,AuthorName' 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这篇已经很多了,下篇继续写
腾讯云开发者
