Python sphinx-build在Windows系统中将rst生成Html文档

1.下载安装Python3

https://www.python.org/downloads/

2.下载Python包SetupTools

检查Python目录下的子目录Scripts是否存在easy_install.exe文件,如果存在请继续第三步,不存在请下载https://pypi.python.org/pypi/setuptools zip包,解压后放到Python安装的根文件夹下面,并该目录加入到环境变量中。

3. 安装Sphinx

启动CMD,并运行命令”easy_install sphinx”,该过程需要一段时间,安装过程中有warning,并长时间等待时,可以按键盘的任意键,继续运行,直到安装完成。

windows下的python安装完成后,会在python的安装目录scripts下生成几个exe文件,其中包括easy_install和pip,

我们将上述路径添加到系统的环境变量后,在正常情况下是可以使用,easy_install等工具的,

个别情况如果出现以下错误可以参照解决,没有报错的忽略:

-----------------------------------------------------------------------------------------------

C:\Python\Scripts>easy_install sphinx
Fatal error in launcher: Unable to create process using '"D:\Python\python.exe
" "C:\Python\Scripts\easy_install.exe" sphinx
主要原因是在使用easy_install等工具时,工具中的默认的python安装路径和系统中的不一致,此时需要我们显式地调用python进行安装即可:

python -m easy_install sphinx

如果想彻底解决可以,可以在cmd下执行“python -m pip install --upgrade pip”解决了问题,我这却不行。

于是使用二进制文件编辑工具修改“pip.exe”,

参考:http://stackoverflow.com/questions/24627525/fatal-error-in-launcher-unable-to-create-process-using-c-program-files-x86

使用HEdit打开,然后搜索“C:\”,找到对应的位置,然后把盘符修改成“D”,保存,再执行"pip","easy_install"命令就OK了

4.安装sphinx_rtd_theme

在cmd中运行“pip install sphinx_rtd_theme”,安装相应的模块。

5. 生成Html文档

准备rst目录结构包含如下,其中docs文件夹包含rst文件。Conf.py存放sphinx-build命令的相关参数,可以根据模板自己文档内容进行修改。

文档结构可以去这里下载

https://github.com/ieflex/newretaildoc

进入文档目录执行命令make html

目录结构包含如下,其中docs文件夹包含rst文件。Conf.py存放sphinx-build命令的相关参数,可以根据模板自己文档内容进行修改。在rst文档中的build目录中生成了根据rst文档创建的html及相关文档。

5. create_html.bat

create_html.bat文件里有两个路径,是python3安装后的路径,这个需要根据自己安装的python3路径进行修改

title create html - 文档生成
COLOR 0A
SET PATH=D:\Python\Python3\Scripts;D:\Python\Python3;%PATH%.
"%CD%"\make html

6. rst文件语法的简单介绍

6.1文件名.ret-->文件名.html

例如:index.rst --->index.html

6.2引用其他rst文件:

.. toctree::
   :maxdepth: 1
   
   agv/index.rst
   android/android.rst
   erp/index.rst
   face/index.rst
   lock/index.rst
   miniprogram/index.rst
   print/index.rst
   scales/index.rst
   zigbee/index.rst
   tb_lcd/index.rst

6.3层级标题

- **首页**

  + 进入首页连接服务器认证
  + 认证成功后等待框消失

6.4 图片 

.. image:: ../picture/android1.png
    :alt: snake
    :width: 540px

其他语法参照

https://www.jianshu.com/p/1885d5570b37

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章