Sphinx初尝

2020-12-07 11:52:23 浏览数 (2)

我们经常可以看到这种的doc文档,简洁大方.作为阅读可谓看着是赏心悦目

那么我能不能自己做一个这样的doc呢,我想是可以的,大家跟着我试试看!

代码语言：javascript复制
https://robomaster-dev.readthedocs.io/zh_CN/latest/python_sdk/beginner_multi_robot.html

最近一位朋友想做个大疆的EP车,我提供一些建议,在看Dji的SDK,我就顺手拿这个来做示范了.

代码语言：javascript复制
https://iridescent.ink/HowToMakeDocs/Basic/Sphinx.html
代码语言：javascript复制
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文档

代码语言：javascript复制
https://docs.python.org/zh-cn/3/

首先创建一个文件夹,为了避免污染环境

先看看目录

在pip

是否分离source和build目录（输入y,选择分离，方便管理)

欢迎使用Sphinx 3.3.0快速入门实用程序。

请输入以下设置的值（只需按Enter

接受默认值（如果在括号中给出）。

选定的根路径：。

您有两个选择来放置Sphinx输出的构建目录。

您可以在根路径中使用目录“ _build”，也可以单独使用

根路径中的“源”和“构建”目录。

有一些提示,自己摁

代码语言：javascript复制
项目名称将在生成的文档中的多个位置出现。
>项目名称：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: 主文档
代码语言：javascript复制
config.py的详细信息
https://www.sphinx-doc.org/en/master/usage/configuration.html

这个是配置文件可以看到是和我创建文件的时候的内容相符

代码语言：javascript复制
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 文件类型

代码语言：javascript复制
运行Sphinx v3.3.0
制作输出目录...完成
建立[mo]：过时的0个po文件的目标
建立[html]：过时的1个源文件的目标
更新环境：[新配置]添加了1个，更改了0个，删除了0个
阅读来源... [100％]索引
寻找过时的档案...找不到
酸洗环境...完成
检查一致性...完成
正在准备文件...完成
写输出... [100％]索引
生成索引... genindex完成
写其他页面...搜索完成
复制静态文件...完成
复制多余的文件...完成
用英语（代码：en）倾销搜索索引...完成
倾销对象清单...完成
建立成功。
HTML页面位于build  html中。

编译过后的目录是这样的

里面有三个html文件,都打开看看

以上是打开的三个网页文档

那我写完就想自动预览文档,咋办?当然可以啦

这个是我的浏览器的位置,你如果也是chrome,可以直接复制我的地址

代码语言：javascript复制
C:Program FilesGoogleChromeApplication

把浏览器的目录加环境变量,自己找

在:end和popd中间加代码

代码语言：javascript复制
:end

        REM ----------------------------------------------
        REM Added by Yunswj - Auto open build file
        REM ----------------------------------------------

        if "%1" == "html" (
        chrome build/html/index.html
        )

popd

改成这样

第一次报错

powershell还是不可以

用cmd打开正常,这个powershell其实更shell一些

此时,我们要看一眼托管以及用他家的主题

代码语言：javascript复制
https://readthedocs.org/

我用Github登录了

就是一个托管平台,巴适的很

代码语言：javascript复制
https://readthedocs.org/projects/yunswj-demo/

这些指令是生成自己的doc

这个是默认生成的doc

这个是源代码

云服务器编译,有点好用

详细设置

可以导入自己的文档(在线)

可以看到有很多详细的选项

代码语言：javascript复制
https://readthedocs.org/dashboard/import/manual/?

可以这样用地址导入

代码语言：javascript复制
https://github.com/readthedocs/template
代码语言：javascript复制
pip install sphinx_rtd_theme

这里我也不托管,先搞一手主题

安装

成功

代码语言：javascript复制
# for using Read the Docs theme
import sphinx_rtd_theme
代码语言：javascript复制
# 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库。

代码语言：javascript复制
pip install recommonmark

pip install sphinx_rtd_theme

安装好，在conf.py中修改下列两个配置：

代码语言：javascript复制
source_suffix = ['.rst', '.md', '.MD']
html_theme = 'sphinx_rtd_theme'

并新增：

代码语言：javascript复制
source_parsers = {
    '.md': CommonMarkParser,
    '.MD': CommonMarkParser,
}
代码语言：javascript复制
https://sphinx-doc-zh.readthedocs.io/en/latest/tutorial.html

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

sphinx 打包 .net python

0 人点赞