Sphinx文档书写(Sphinx+gitee+read the Docs)
1 创建文件夹 ,例如MYDOCS
2 安装sphinx,首先确保安装了python和pip。
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx
3 当前目录下打开终端,命令:sphinx-quickstart
4 编译,终端输入 .\make html
5 sphinx-autobuild 编译
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild #安装
sphinx-autobuild source .\build\html #编译文件
然后可以使用终端输出的ip地址和端口号进行访问,效果同上。
6 主题更改
Sphinx主题官网:https://sphinx-themes.org/
随便点一个主题,进入按照说明安装,例如:
pip install sphinx-rtd-theme
修改conf.py 文件
html_theme = 'sphinx_rtd_theme'
重新编译后,可以看到主题更新了~
7 markdown支持
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple recommonmark
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx_markdown_tables
修改conf.py 文件extensions = ['recommonmark','sphinx_markdown_tables']
8 markdown编写
可参考官网。
9 gitee推送
如果前面使用了extensions = ['recommonmark','sphinx_markdown_tables']
这两个markdown插件需要多做两件事情:
(1) 根目录创建.readthedocs.yml
,内容为:
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: source/conf.py # 这个路径根据`conf.py`的路径写,一般放在source目录
# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml
# Optionally build your docs in additional formats such as PDF
formats:
- pdf
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: requirements.txt # 这个路径根据`.requirements.txt`的路径写,一般放在根目录
(2) 根目录创建.requirements.txt
,内容(根据使用的插件添加)为:
sphinx
sphinx-rtd-theme
recommonmark
sphinx_markdown_tables
将MYDOCS
文件夹下(build文件夹下可不推送)的内容推送到gitee,使用tortoisegit比较方便。注意:gitee仓库需要是公开的。
10 Read the Docs
Read the Docs官网。我的项目->Import a Project->手动导入->填写gitee仓库信息和项目名称->构建->最终可以点击阅读文档进行访问。可能构建会出错,把conf.py
文件中的extensions = ['recommonmark','sphinx_markdown_tables']
改为extensions = ['recommonmark']
最后
当然,书写文档的工具有很多,例如Hexo,Mkdocs,Teadocs,大同小异,只是他们依赖的语言环境不同。仓库也可以使用github,gitlab等进行托管。