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

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