標籤:div 路徑 clu trait ima basic port toc value
在使用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 osimport djangoimport syssys.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