python代碼docstring產生文檔之sphinx

來源:互聯網
上載者:User

標籤: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

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.