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

蔚落 2022-01-29 00:45 270阅读 0赞

# 1.下载安装Python3 #

[https://www.python.org/downloads/][https_www.python.org_downloads]

# 2.下载Python包SetupTools #

检查Python目录下的子目录Scripts是否存在easy\_install.exe文件，如果存在请继续第三步，不存在请下载[https://pypi.python.org/pypi/setuptools][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][https_github.com_ieflex_newretaildoc]

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

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2llZmxleA_size_16_color_FFFFFF_t_70][]

# 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][https_www.jianshu.com_p_1885d5570b37]

[https_www.python.org_downloads]: https://www.python.org/downloads/
[https_pypi.python.org_pypi_setuptools]: https://pypi.python.org/pypi/setuptools
[https_github.com_ieflex_newretaildoc]: https://github.com/ieflex/newretaildoc
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2llZmxleA_size_16_color_FFFFFF_t_70]: /images/20220129/eb6994eac1ed48a29be0bbcdb0622a67.png
[https_www.jianshu.com_p_1885d5570b37]: https://www.jianshu.com/p/1885d5570b37