时间:2021-07-01 10:21:17 帮助过:46人阅读
用Sphinx编写技术文档 大家会发现,如果一个项目主要是用Python写的,其文档都很类似,比如:Python在线的HTML官方手册。这些项目的文档都来源于一个很不错的项目:Sphinx。这个Sphinx特指Sphinx doc这个项目(另一个也叫Sphinx的search的项目,虽然都叫一个
大家会发现,如果一个项目主要是用Python写的,其文档都很类似,比如:Python在线的HTML官方手册。这些项目的文档都来源于一个很不错的项目:Sphinx。这个Sphinx特指Sphinx doc这个项目(另一个也叫Sphinx的search的项目,虽然都叫一个名字)。
官网:http://sphinx-doc.org/
以下出现Sphinx的地方,都特指Sphinx doc这个项目
这里就列举个人关心的几个特性:
就是rst的语法,这里就列举几个常用的:
rst如下:
一级标题 ======== 二级标题 -------- 三级标题 ^^^^^^^^
效果如下:
习惯上,可以用以下字符:“= - ` : ‘ ” ~ ^ _ * + # < >”。最好能约定个依次标题等级。
rst如下:
* 列表1 * 列表2 * 列表3
效果如下:
列表写法除了用“*”,还可以用:“-”,“+”,最后效果一样。
上面说的是无序列表,如果想用有序列表,可以用“#.”。
rst如下:
#. 列表1 #. 列表2 #. 列表3
效果如下:
rst如下:
===== ===== ===== 第1列 第2列 第3列 ===== ===== ===== 8 1 6 3 5 7 4 9 2 ===== ===== =====
效果如下:
第1列 | 第2列 | 第3列 |
---|---|---|
8 | 1 | 6 |
3 | 5 | 7 |
4 | 9 | 2 |
rst如下:
.. image:: images/ball1.gif
效果如下:
展示代码示例,经常会用到:
rst如下:
:: print 'Hello World!'
效果如下:
print 'Hello World!'
rst如下:
.. code-block:: python :linenos: print 'Hello World!'
效果如下:
print 'Hello World!'
rst如下:
.. literalinclude:: code/example.js :language: javascript :linenos:
效果如下:
直接下载该RST本身。
rst如下:
:download:`sphinx.rst`
效果如下:
sphinx.rst
example1对应sphinx.rst所在目录下的example1.rst文件,example2类似。
rst如下:
.. toctree:: :maxdepth: 2 example1 example2
效果如下:
- 二级标题1
- 二级标题2
可以用于跨rst文档间的内容互相引用。这里以本文档内为例。
rst如下:
.. _my-reference-label: 用Sphinx编写技术文档 ==================== 很长的文字内容 点击回到顶部, :ref:`my-reference-label`.
效果如下:
点击回到顶部, 用Sphinx编写技术文档 .
rst如下:
*斜体*
效果如下:
斜体
rst如下:
**粗体**
效果如下:
粗体
斜杠是为了空格转义,最后显示无空格。
rst如下:
H\ :sub:`2`\ O
效果如下:
H2O
rst如下:
E = mc\ :sup:`2`
效果如下:
E = mc2
参见
根据上面的介绍,其实常用的语法不多,现在直接用下,自己感受下吧!
常用Python安装方式,创建个文件夹,执行命令,按提示自己选择即可。
pip install Sphinx mkdir docs cd docs sphinx-quickstart
根据提示输入相应参数即可,可以一路默认。
编辑index.rst,只写入以下内容
用Sphinx编写技术文档 ==================== 使用场景 --------
很简单,默认支持就很好。
make html python -m SimpleHTTPServer 9527
直接浏览器访问9527端口,就可以看到类似Python官方文档的效果。
麻烦些,需要依赖库,且需要简单修改下配置。
pip install rst2pdf
Linux下的Makefie:
Windows下的批处理:
make pdf python -m SimpleHTTPServer 9527
参见
有关PDF的更多配置,可以阅读这个文档:http://ralsina.me/static/manual.pdf
Slide就是我们常说的演示文档,如:Windows下的PowerPoint(PPT);Mac下Keynote等等。这里用Sphinx生成在线的HTML5形式的Slide,操作也相对简单,也是需要依赖库和简单修改下配置。
pip install hieroglyph
Linux下的Makefie:
make slides python -m SimpleHTTPServer 9527
参见
有关Slide的更多信息,可以直接查看这个项目:https://github.com/nyergler/hieroglyph
直接拿来主义,直接用别人写的Trac的样式
cp tracsphinx.css _static/
make html python -m SimpleHTTPServer 9527
直接浏览器访问9527端口,就可以看到类似Trac的官方样式效果。
可以直接看Python项目模板:https://github.com/akun/aproject/只看docs目录即可。
这里提到的几个核心文件示例如下:
另外推荐一个服务:https://readthedocs.org/
如果你的项目研发文档用Sphinx写的,可以用来做文档的持续集成,相当方便。
这个《软件构建实践系列》就是用的这个服务。
这是一篇很简单的项目推广文章,在自己的Python项目中把Sphinx用起来吧!
当然Sphinx不仅支持Python源码的Domain,而且支持C、C++、JavaScript等Domain,即使没有你所用的语言的Domain,它本身还支持写插件扩展,所以其它类型语言的项目也不妨用一下。
注解
这篇是个人总结的《软件构建实践》系列的一篇文章,更多更新内容,可以直接在线查看:http://pm.readthedocs.org。并且部分内容已经公布在GitHub上:https://github.com/akun/pm
原文地址:用Sphinx编写技术文档, 感谢原作者分享。