使用sphinx+markdown+readthedocs+github来编写文档
1.效果预览
https://how-to-use-sphinx-write.readthedocs.io/zh_CN/latest/
2.安装
2.1准备
安装之前假设你已经安装好了python3
- sphinx版本:3.4
- 以下以Linux命令为主,window可以手动创建目录,然后在cmd执行pip和初始化即可.
#安装sphinx/主题/markdown
pip install sphinx recommonmark sphinx_rtd_theme
#创建一个目录docs
mkdir docs
#切换至docs目录
cd docs
#初始化一个sphinx
sphinx-quickstart
在执行命令sphinx-quickstart的时候，会让你输入配置，除了以下几个个性化配置外，其他的都可以按照默认的来（回车默认配置）。
> Separate source and build directories (y/n) [n]:n
> Project name: how-to-use-sphinx
> Author name(s): jonnyan404
> Project release []: 0.1
> Project language [en]: zh_CN
执行完毕后，就可以看见创建的工程文件
- _build：文件夹，当你执行
make html的时候，生成的html静态文件都存放在这里 - _static：文件夹：图片,js等存放地址
- _templates：文件夹:模板文件存放
- make.bat：bat脚本
- Makefile:编译文件
- index.rst:索引文件,文章目录大纲
- conf.py:配置文件
2.2编写文章
在docs目录下新建hello.rst,内容如下:
hello,world
=============
如果会markdown语法,无需学习rst语法,可参考文末语法转换网站.
index.rst修改如下:
.. toctree::
:maxdepth: 2
hello
然后在docs目录下执行 make html,进入 _build/html 目录后用浏览器打开 index.html
2.3更改主题和添加md支持
vim conf.py #更改如下配置:
html_theme = "sphinx_rtd_theme"
extensions = ['recommonmark']
然后再次运行 make html 即可.
关于markdown的用法形式与rst一样,直接更换后缀并在文件内已markdown语法写内容即可.
3.与GitHub联动
上传代码至GitHub仓库,然后去 https://readthedocs.org/ 注册账号,并关联GitHub仓库.
然后需要在GitHub仓库根目录下,增加一个名称为 .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: docs/conf.py
# 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: docs/requirements.txt
再去 docs 目录下,新建一个名称为 requirements.txt 的文件,在这个文件内增加你所使用的包名称.
例如我的是:
sphinx
sphinx-rtd-theme
recommonmark
如果以上两个文件不添加,那么自动构建出来的文章,与你在本地的生成的会不一致,因为 readthedocs 网站默认使用mkdocs来构建.
