一直在使用MarkDown來簡單記錄相關操作文檔，嘗試使用.rst(reStructuredText)文件來記錄一下
- 安裝
pip install sphinx
安裝中會自動下載安裝相關依賴，耗時會多點讲逛。
- 測試安裝
- 創(chuàng)建一個文件夾docs，進入該文件夾，在cmd執(zhí)行命令揣云，創(chuàng)建一個新的文檔目錄用來測試
sphinx-quickstart
- 會在當前目錄下創(chuàng)建相關的文件清單
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── ystatic
└── ytemplates
4 directories, 4 files
- 文件介紹
- Makefile：編譯過代碼的開發(fā)人員應該非常熟悉這個文件，如果不熟悉冰啃，那么可以將它看作是一個包含指令的文件邓夕，在使用 make 命令時，可以使用這些指令來構建文檔輸出阎毅。
- build：這是觸發(fā)特定輸出后用來存放所生成的文件的目錄焚刚。
- source：這是存放.rst文件的目錄。
- conf.py：這是一個 Python 文件扇调，用于存放 Sphinx 的配置值矿咕，包括在終端執(zhí)行 sphinx-quickstart 時選中的那些值。
- index.rst：文檔項目的 root 目錄狼钮。如果將文檔劃分為其他文件碳柱，該目錄會連接這些文件。
- ystatic:：靜態(tài)資源文件
- ytemplates：模板文件
- 執(zhí)行下面命令熬芜，在build文件夾下轉換成html文檔
sphinx-build -b html ./source ./build
執(zhí)行構建命令莲镣，將source目錄下的rst資源文件，轉換為html文件到build目錄下
上面演示了簡單的生成步驟
進一步了解
index.rst 文件
該文件是入口涎拉，新增的文件要構建瑞侮，需要在該文件里面配置。在 index.rst 文件中的主標題之后鼓拧，有一個內容清單半火，其中包括 toctree 聲明。toctree 是將所有文檔匯集到文檔中的中心元素季俩。如果有其他文件存在钮糖，但沒有將它們列在此指令下，那么在構建的時候酌住，這些文件不會隨文檔一起生成店归。
加入我們下載有一個新增的文件example.rst，想要進行構建赂韵，我們需要將它列在index.rst的文件清單 toctree 中娱节，不需要后綴名。示例如下：
.. toctree::
:maxdepth: 2
:caption: Contents:
example # 與上面保留一行空行才可生效
example.rst文件放在source文件下祭示，構建目錄如下：
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── example.rst
├── index.rst
├── ystatic
└── ytemplates
4 directories, 5 files
此時執(zhí)行以下命令肄满，重新編譯
E:\docs>make html
Running Sphinx v1.7.5
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
The HTML pages are in build\html.
這是最簡單的新增一個文件在index.rst中谴古，具體的排版細節(jié)待完善。稠歉。掰担。
