本文介紹如何使用Sphinx，簡單將在套件裡辛辛苦苦寫的Python docstring轉換成HTML，直接變成漂亮的說明網站～
前置作業
- 內含docstring的套件（可用參考網站的參考套件範例：python-dev-setup）
- 建立虛擬環境（跟套件在同一個目錄底下比較方便，參考網站是將兩者都放在根目錄下）
按順序在終端機輸入以下指令
$ pip install vitualenv # download vitualenv
$ virtualenv venv # create virtual environment
$ . venv/bin/activate # activate virtual environment
$ pip3 install autopep8
$ pip3 install pylint
$ pip3 install coverage
$ pip3 install -U sphinx
$ pip3 install sphinx_rtd_theme
以上的動作是因為，開發環境需要Python2.7版本，為了不與自己電腦的Python3.6版本混在一起，於是使用vitualenv建立一個名叫venv的虛擬環境（可自行命名），再下載所需套件與Sphinx，其中Sphinx_rtd_theme是一種Sphinx的主題風格
sphinx-quickstart
建立好虛擬環境後，可以開始使用sphinx-quickstart，輸入以下指令
$ . venv/bin/activate
$ mkdir docs
$ cd docs
$ sphinx-quickstart # queries on basic setup shall starts
欢迎使用 Sphinx 3.4.1 快速配置工具。 （最新版可接受python3.6.9的註解型態的版本，例如： log(listA) -> list:）
獨立的源文件和建構目錄（y/n） [n]: y
項目名稱:
作者名稱:
項目發行版本 []:
項目語種 [en]: en
設定autodoc路徑
上述跑完後會出現一些檔案，先修改docs/source/conf.py的內容，找到 Path setup ，修改成以下內容
import os
import sys
sys.path.insert(0, os.path.abspath('../../')) # 參考圖1檔案的位階
# this conf.py is in ./docs/source/conf.py
# therefore our source code is up 2 level then the directory of python source code is the i.e. ./python_dev_setup
設定HTML主題
在./docs/source/conf.py
html_theme = 'sphinx_rtd_theme'
設定型態提示風格
同樣在./docs/source/conf.py
extensions = [ sphinx.ext.napoleon ]設定index.rst
內容完全照搬就對了～頂多變更標題
Python Dev Environment in VSCode （標題）
====================================================================
.. toctree::
:maxdepth: 2
:caption: Readme
readme
.. toctree::
:maxdepth: 2
:caption: Docstring
docstring/modules
.. toctree::
:maxdepth: 2
:caption: Index
indices
建立readme.rst
手動建立docs/source/readme.rst ，內容為
.. include:: ../../README.rst
如此一來readme.rst就會參考在根目錄下（跟套件同一位階）的README.rst全部內容
建立indices.rst
手動建立docs/source/indices.rst，內容為
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
建立Python 說明文件
$ . venv/bin/activate
$ rm -Rf docs/build
$ rm -Rf docs/source/docstring
$ sphinx-apidoc -f -o docs/source/docstring/ python_dev_setup # this is the steps where the docstring/modules going to be filled with our code docstring
其中是指python_dev_setup 套件路徑，注意要與前面的路徑用空格分開
最後輸入
$ cd docs && make html && cd ..
看到下圖代表完成，可進入該路徑點進去看看網頁長怎樣（見證奇蹟的一刻！）
Project裡含多個套件的情況
在sphinx-quickstart的階段輸入正確的project名稱，或是選擇在docs/source/conf.py裡面找到Project information 修改project參數
先照著標題sphinx-quickstart做直到以下兩條指令前停
$ sphinx-apidoc -f -o docs/source/docstring/ package
$ cd docs && make html && cd ..
只要將上述指令中的package換上自己的套件位置並執行到第二行，執行完後可再換同位址不同套件的位置再執行建立HTML，最後生成兩個套件都在同一個HTML裡
結語
使用Sphinx快速生成Python說明文件實在是太幸福了XD 非常值得花時間摸索
參考網站
- Python Doc Generation with Sphinx：https://medium.com/@andreas.007/automate-documentation-in-python-925c38eae69f
- Python Dev Setup：https://gitlab.com/suekto.andreas/python-dev-setup
- Python — Virtualenv虛擬環境安裝：https://medium.com/python4u/python-virtualenv%E8%99%9B%E6%93%AC%E7%92%B0%E5%A2%83%E5%AE%89%E8%A3%9D-9d6be2d45db9
- 使用sphinx快速為你python註釋生成API文檔: https://blog.csdn.net/sinat_29957455/article/details/83657029?fbclid=IwAR3-yyTMzAYMJOCv99AQxDn35hR3Xm5Y1KI_1bTvr2Z5kCvDl0nQS0yR_rY
LEODFLAG's Blog 