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 themeimport 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

这篇已经很多了,下篇继续写

赞 (0)

相关推荐