准备工具
Python 3.4
Visual Studio Code
Git
1.安装 sphinx和自动build插件
pip install sphinx sphinx-autobuild
2.安装 restructuredtext-lint
pip install restructuredtext-lint
3.VScode插件安装
3.1安装插件 reStructuredText
它提供了.rst文件的预览功能十分便捷。
3.2安装插件 Table Formatter
由于reStructuredText做表格特别麻烦，这个插件可以帮助你做表格，只需要把关键的标记写对，其余的都会自动补全而且效果十分美观。
注意： 插件安装完成之后需要点击重新加载方能生效
4.新建写作项目
sphinx-quickstart
安装主题
pip install sphinx_rtd_theme
实时预览
sphinx-autobuild docs docs/_build/html
注意：
docs是你项目的文件夹名称，需要在项目的上一级目录执行以上指令。
运行成功后，访问 http://127.0.0.1:8000
参考资料
[1] http://avnpc.com/pages/writing-best-documentation-by-sphinx-github-readthedocs
写最好的文档：Sphinx + Read the Docs
[2] https://www.jianshu.com/p/78e9e1b8553a
如何用 ReadtheDocs、Sphinx 快速搭建写书环境
[3] http://www.sphinx-doc.org/en/stable/config.html
The build configuration file
[4] https://github.com/vscode-restructuredtext/vscode-restructuredtext/blob/master/docs/sphinx.md
reStructuredText入门
[5] http://www.pythondoc.com/sphinx/rest.html
网友评论