本文介紹如何使用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