Python有個自帶的工具可以生成Python的項目文檔叫pydoc,但是我覺得最好用的還是Python-Sphinx,這裡我們就講一下python-Sphinx的使用。
Sphinx可以自動獲取代碼中的(''' ''' 註釋),自動生成文檔。先看看最後要成為的效果,先提起你的興趣
安裝Sphinx
pip install Sphinx
寫個我們需要生成文檔的項目-代碼建一個測試項目code, 下面有兩個Python文件test1.p y和test2.py
(venv) allenwoo@~/renren$ ls code venv (venv) allenwoo@~/renren$ ls code/ test1.py test2.py
test1.py代碼:
# -*-coding:utf-8-*- class Test1: ''' 我是測試類,負責測試 ''' def hello(self): ''' 負責打印Hello, 人人可以學Python :return: ''' print("人人可以學Python") def renren(self): ''' 測試Sphinx自動生成文檔 :return: ''' print("自動生成文檔") class Test2: def test_2(self): ''' 我也不知道寫什麼好,反正我們這裡是用來寫文檔的 :return: ''' print("文檔自動生成測試2") def renren_2(self): ''' 所以我們開發的時候就應該在這裡寫好文檔,然後用Sphinx自動生成 :return: ''' print("自動生成文檔2")
test2.py代碼:
# -*-coding:utf-8-*- def init_test: ''' 用於初始化項目測試,不需要任何參數 :return: ''' print("初始化項目") def start: ''' 啟動項目入口, :return: ''' test(3) def test(v): ''' 項目運行主要函數,需要傳入一個參數\n v:
使用Python-Sphinx doc
1. 選擇配置除了以下項目外,其他的我都使用了默認值:
(venv) allenwoo@~/renren/doc$ sphinx-quickstart Welcome to the Sphinx 1.5.5 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: . > Separate source and build directories (y/n) [n]: y > Project name: Code Pro > Author name(s): Allen Woo > Project version : 1.0 > Project language [en]: zh_cn > autodoc: automatically insert docstrings from modules (y/n) [n]: y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y > coverage: checks for documentation coverage (y/n) [n]: y > viewcode: include links to the source code of documented Python objects (y/n) [n]: y
2.配置conf.py在source/conf.py文件中加入如下代碼, 導入自己的項目路徑
import os import sys sys.path.insert(0, os.path.abspath('./../../code'))
3. 生成rst文件注意:-o 後面跟的是保存rst文件的路徑, 你的index.rst在哪個目錄,那你就指定哪個目錄。然後在後面的是你的項目(代碼)路徑
(venv) allenwoo@~/renren/doc$ sphinx-apidoc -o ./source ../code/ Creating file ./test1.rst. Creating file ./test2.rst. Creating file ./modules.rst.
4. 最後執行make html,生成html文件
(venv) allenwoo@~/renren/doc$ make html Running Sphinx v1.5.5 loading translations [zh_cn]... done loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 0 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found no targets are out of date. build succeeded. Build finished. The HTML pages are in build/html.
OK!
5.現在我們用瀏覽器打開doc/build/html/index.html,如下:如果你也和我一樣覺得頁面UI很醜,那就繼續看下一步,我們安裝一個theme(主題)
主頁面
Paste_Image.png
文檔頁面
Paste_Image.png
源碼頁面
Paste_Image.png
安裝Sphinx主題python sphinx的主體包郵很多,我最喜歡 readthedocs風格的:這種風格的sphinx主體包叫sphinx_rtd_theme可以下載安裝,也可以命令安裝。
命令安裝:
pip install sphinx_rtd_theme
下載地址:https://github.com/rtfd/sphinx_rtd_theme注意:下載安裝的配置和使用命令安裝的不一樣,具體可以看GIthub上的文檔:
配置:編輯我們的source/conf.py導入模塊:
import sphinx_rtd_theme
將 html_theme = "alabaster"改成如下,在加上html_theme_path
html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
最後我們再執行一次:make html然後再訪問文檔,發現裡面變的好看了,是不是?
好了,我們自動生成文檔久到這裡了