一直在使用MarkDown來簡單記錄相關(guān)操作文檔，嘗試使用.rst(reStructuredText)文件來記錄一下

• 安裝

pip install sphinx

安裝中會自動下載安裝相關(guān)依賴，耗時會多點。

• 測試安裝

1. 創(chuàng)建一個文件夾docs，進入該文件夾，在cmd執(zhí)行命令，創(chuàng)建一個新的文檔目錄用來測試

sphinx-quickstart

2. 會在當(dāng)前目錄下創(chuàng)建相關(guān)的文件清單

.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── ystatic
    └── ytemplates

4 directories, 4 files

3. 文件介紹

• Makefile：編譯過代碼的開發(fā)人員應(yīng)該非常熟悉這個文件，如果不熟悉，那么可以將它看作是一個包含指令的文件，在使用 make 命令時，可以使用這些指令來構(gòu)建文檔輸出。
• build：這是觸發(fā)特定輸出后用來存放所生成的文件的目錄。
• source：這是存放.rst文件的目錄。
• conf.py：這是一個 Python 文件，用于存放 Sphinx 的配置值，包括在終端執(zhí)行 sphinx-quickstart 時選中的那些值。
• index.rst：文檔項目的 root 目錄。如果將文檔劃分為其他文件，該目錄會連接這些文件。
• ystatic:：靜態(tài)資源文件
• ytemplates：模板文件

3. 執(zhí)行下面命令，在build文件夾下轉(zhuǎn)換成html文檔

sphinx-build -b html ./source ./build

執(zhí)行構(gòu)建命令，將source目錄下的rst資源文件，轉(zhuǎn)換為html文件到build目錄下

上面演示了簡單的生成步驟

進一步了解

index.rst 文件
該文件是入口，新增的文件要構(gòu)建，需要在該文件里面配置。在 index.rst 文件中的主標(biāo)題之后，有一個內(nèi)容清單，其中包括 toctree 聲明。toctree 是將所有文檔匯集到文檔中的中心元素。如果有其他文件存在，但沒有將它們列在此指令下，那么在構(gòu)建的時候，這些文件不會隨文檔一起生成。

加入我們下載有一個新增的文件example.rst，想要進行構(gòu)建，我們需要將它列在index.rst的文件清單 toctree 中，不需要后綴名。示例如下：

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   
   example  # 與上面保留一行空行才可生效

example.rst文件放在source文件下，構(gòu)建目錄如下：

.
├── 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é)待完善。。。

TODO conf.py配置文件說明