Sphinx快速入门¶
- date
2018/04/12
- author
高志军
Sphinx是一个静态网页发布工具,可将rST和md文件,发布为各类常见的用户帮助如联机帮助,用户手册等。
安装Sphinx¶
快速新建项目(以Mac系统为例,Window系统类似)¶
在桌面上创建一个文件夹,并命名为 sphinx-demo
在Terminal中浏览至上述文件夹,并运行命令:
sphinx-quickstart
在对话框式的选择中,Y/N的选项,选Y;如果询问配置,直接复制[]中的内容,如[.rst],则填写.rst
新建成功后,则会得到如图所示的文件夹结构
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
往项目中添加内容¶
浏览至 source 文件夹,并在其根目录下创建新文件夹demo
在上方 demo 文件夹中,新建test.rst文件,并在其中输入如下内容:
=======================
这是Sphinx的测试
=======================
我爱学习Sphinx
打开source文件中的 index.rst,将test.rst的文件添加至目录中,具体如下:
在Terminal中运行编译命令
sphinx-build -b html source build
编译成功的话,在 build 文件夹中则有刚才发布的网站
修改主题¶
打开 source 文件夹中的conf.py,并找到主题配置行 html_theme = ‘alabaster’
从内置主题中挑选需要的主题,如 bizstyle,将其改为 html_theme = ‘bizstyle’
重新运行发布命令后,则可得到新主题的样式的帮助文档
注解
Sphinx内置主题的样式可见:http://www.sphinx-doc.org/en/master/theming.html#using-a-theme。还可以安装其他主题,或者按照需要制作自己的主题。
安装ReadtheDoc同款主题¶
如果喜欢 readthedocs.org 的主题,可以按照如下方式安装
pip install sphinx_rtd_theme
安装之后,再按照上述步骤,将 conf.py
中的主题行,修改为html_theme = ‘sphinx_rtd_theme’,再运行 sphinx-build
命令重新发布即可。
实现帮助文档公网可访问¶
执行 sphinx-build
命令后,sphinx会将rst的内容,发布为静态网站。只需将 build 文件夹中的文件,托管至github,即可实现公网访问。
由ReadtheDocs执行发布命令¶
每次更新后,都需执行 sphinx-build
命令,并重新上传至Github,较为麻烦。这个工作可以由ReadTheDocs平台自动化完成。
注册ReadTheDocs账号
将Github账号关联到ReadtheDocs
将source文件中的内容,上传至github中的某个repo中
选择github的相应ropo,自动创建webhook
后续每次源文件内容有变化后,ReadtheDoc均可以自动发布最新的版本
更多内容参见ReadtheDocs官方文档:https://docs.readthedocs.io/en/latest/getting_started.html
下次课内容
reStructedText
自定义主题
制作主题
发布为PDF等其他样式
预习:
HTML,CSS
Jinjia 模板语言
参考资料
[Sphinx官方教程]: http://www.sphinx-doc.org/en/master/usage/quickstart.html
演示本地修改,自动发布。