必备环境:Python3.5+以上,jinjia2
本人使用pip安装sphinx,未安装pip的请安装pip
pip install -U sphinx,
安装完成后,使用下命令检查是否安装成功过是否安装成功!
sphinx-build --version
如果需要使用最新的开发版,则使用命令:
pip install -U --pre sphinx
使用sphinx-quickstart开始创建文档结构:
在桌面创建C:\Users\X250\Desktop\下创建一个sphinx文件夹,然后执行下面的命令:
sphinx-quickstart
static dir 【_】,Project release 【】 我这里直接回车。
其他的地方几乎一直输入y即可。
此时sphinx文件夹下将生成以下文件:
进入到source文件夹,index.rst为主文档,config为主目录,如下图:
index.rst的主要功能是作为欢迎页面,并包含“目录树”(或toctree)的根。
欢迎页面的内容以后再说,现在让sphinx生成html,让我们先预览一下,其生成的html,执行下面的命令:
用浏览器打开index.html,结果如下:
make html 也可以用 sphinx-build -b html sourcedir builddir 进行代替。
注意,要将sourcedir替换为source,即包含有conf.py和index.rst的目录
make.bat和makefile实际上是sphinx-quickstart脚本创建的,其目的是能让我们更快的执行相应的命令,
其根本也是使用sphinx-build命令,只是简化了我们的输入操作。
make html无法生成单个html,有些要求下使用改命令很不方便。
使用 make singlehtml 则会生成单个html,这个html包含了所有内容,很给力!