python代碼docstring生成文檔之sphinx
阿新 • • 發佈:2018-04-23
basic toc bash 當前 highlight start IE 我們 項目
在使用python中,我們一般在模塊,類,函數下使用docstring添加字符串說明性文檔,使開發人員更好的可以看懂此代碼是做什麽用的。然而寫了那麽多的註釋,我們想要一篇文檔怎麽辦,第一種辦法不可能將寫完的註釋直接手動的ctrl+c ctrl+v的,此時sphinx就出現了,解決了這一問題。
要想使用它,首先得需要安裝它,安裝方式:
pip install sphinx
安裝完成之後,在主項目下創建docs文檔
#創建完docs項目並切換到 docx目錄下 cd docx
在 docx下運行 sphinx-quickstart
之後會提示讓對項目進行一些設置,以生成項目的配置文件,下面是一個推薦的配置:
> Root path for the documentation [.]: doc # 在當前目錄下新建doc文件夾存放sphinx相關信息 > Separate source and build directories (y/n) [n]: # 默認,直接回車 > Name prefix for templates and static dir [_]: > Project name: python123 # 輸入項目名稱 > Author name(s): 123 # 作者 > Project version: 1.0 # 項目版本 > Project release [1.0]: > Project language [en]: # 默認,回車 > Source file suffix [.rst]: > Name of your master document (without suffix) [index]: > Do you want to use the epub builder (y/n) [n]: > autodoc: automatically insert docstrings from modules (y/n) [n]: y # 這個很重要,輸入y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: > coverage: checks for documentation coverage (y/n) [n]: > pngmath: include math, rendered as PNG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: y # 很重要,輸入y,表示將源碼也放到文檔中,你看很多python的模塊的文檔,其實都是包含代碼的。 > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]:
之後會在doc目錄下生成如下文件
docs build doctrees html source _static _templates conf.py index.rst make.bat Makefile
修改conf.py
import os import django import sys sys.path.insert(0, os.path.abspath(‘..‘)) #註釋掉 sys.path.insert(0, os.path.abspath(‘../..‘)) #更改成這個路徑
修改index.rst 生成文檔都是在index.rst文件下生成,目前測試文件
Welcome to cetc-portraiting‘s documentation! ============================================ .. toctree:: :maxdepth: 2 :caption: Contents: .. automodule:: rest_server.views.basic # model類.py文件 :members: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
最後在docs目錄下直接輸入
make html
編譯成功,進入docs目錄,點擊bulid目錄,進入html目錄,查看index.html,就可以看見文檔html了。沒有截生成完的圖片,故看不了實現效果。
python代碼docstring生成文檔之sphinx