文档构建
本文档选择使用Sphinx来进行构建,支持以 reStructuredText 和 Markdown
格式编写
本地构建
拉取文档
若您是阅读者:
打开终端,运行以下命令:
git clone https://github.com/Lichee-Pi/xxx.git
若您是文档贡献者:
建议您 fork 我们github上的文档项目后拉取到本地,便于发起 Pull Request。
2. 安装依赖
首先我们需要通过pip安装Sphinx
pip install Sphinx
若您没有安装pip,请参照 pip 安装接着安装本文档的模块依赖
pip install sphinx_rtd_theme
用于支持文档主题
pip install recommonmark 用于支持Markdown文本格式
3. 构建
cd Lichee-Zero-Doc-zh-CN
# windows
.\make.bat html
# linux
make html
构建完成,进入 _build --> html --> index.html
打开以浏览器浏览即可。
技术文档贡献
若您有意向贡献您的实践经验,请参照 todolist
以reStructuredText编写文档
.rst
文件是轻量级标记语言的一种,被设计为容易阅读和编写的纯文本,并且可以借助Docutils这样的程序进行文档处理,也可以转换为HTML或PDF等多种格式,或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。
在本文档中, .rst
文件配合sphinx工具以及readthedoc主题,具有较为丰富的文本表现。
此外,与Markdown对比来看:
- RST更适合于构建完整较大的文档,Markdown更适用于构建单页应用
- RST格式更为丰富,Markdown更为简洁
- RST格式要求稍高于Markdown
reStructuredText语法请参考 quick reStructuredText
个人建议您也可以通过查看 Read theDocs主题示例,配合其github的编辑源码模式,可更直观地进行对照、借鉴。
- 另: RST的表格对于中文支持不好,个人推荐借助 pytablewriter 来生成中文表格
# coding: utf-8
import pytablewriter
writer = pytablewriter.RstGridTableWriter()
writer.table_name = "example_table"
writer.header_list = ['水果', '价格', '数量']
writer.value_matrix = [
['香蕉', '1', '5'],
['苹果', '1', '6'],
['草莓', '1', '7'],
]
writer.write_table()
渲染为:
.. table::
+----+----+----+
|水果|价格|数量|
+====+====+====+
|香蕉| 1| 5|
+----+----+----+
|苹果| 1| 6|
+----+----+----+
|草莓| 1| 7|
+----+----+----+
以Markdown编写文档
Markdown语句较为简明,互联网上也有大量的辅助工具与教程;
个人推荐您使用 vscode配合插件Markdown All in One,或使用
typora ,笔者使用体验较为舒适
一点小提醒
若您单纯使用Markdown书写,无需注意以下所有内容;
若您 想用Markdown而不涉及rst及其语法 构建您的 个人文档
时,建议您使用 Mkdocs 替代sphinx,参阅 readthedocs buildprocess;若您将Markdown文件加入sphinx的构建行列,请注意以下两条:
要使用sphinx所提供的特性时,如:
Tip
15% if the service is good.Error
Does not compute.请将其标为代码片段,代码类型为:eval_rst,sphinx将会将此片段作为rst文本进行解析:
```eval_rst .. Tip:: 15% if the service is good. .. Error:: Does not compute. ```
sphinx对Markdown的表格支持不够完全,请使用上一条所用方法,以rst语法来绘制表格