標籤: docstring

Linux、Python、未分類

使用Sphinx生成Python說明文件

Posted on by leodflag

本文介紹如何使用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
圖1.資料階層

設定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 非常值得花時間摸索

參考網站

0